# mycloudbox

**Repository Path**: yang_tao_code/mycloudbox

## Basic Information

- **Project Name**: mycloudbox
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# mycloudbox

**一个开箱即用的私有云盘 · 单文件部署 · 简体中文界面**

`mycloudbox` 基于开源项目 [FolderHost](https://github.com/MertJSX/folderhost) v26.11.0 二次开发，
后端为 Go 单二进制（内嵌前端），前端为 React 19 + Vite。
无外部依赖、无需数据库服务，上传下载、在线预览、代码编辑、用户权限、回收站一应俱全。

> 本仓库对应 **v1** 版本：在上游基础上完成界面全量中文化（约 360 处文案），
> 并补充了部署、内网穿透与安全审计文档。

---

## 目录

- [功能特性](#功能特性)
- [与上游项目的差异](#与上游项目的差异)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [部署为 Windows 服务](#部署为-windows-服务)
- [公网访问（内网穿透）](#公网访问内网穿透)
- [安全须知](#安全须知)
- [常见问题](#常见问题)
- [许可证](#许可证)

---

## 功能特性

| 模块 | 说明 |
|---|---|
| 文件管理 | 上传（大文件分片）、下载、新建、重命名、移动、复制、删除、批量操作 |
| 在线预览 | 图片、视频、音频、PDF、文本；Markdown 渲染 |
| 在线编辑 | 内置 Monaco 编辑器，支持 30+ 语法高亮，多人实时协同 |
| 压缩解压 | zip 打包与解包，支持解压进度推送 |
| 回收站 | 删除可恢复，支持按时间自动清理、容量上限 |
| 用户与权限 | 20 项细粒度权限（读写、上传下载、改名、回收站、用户管理、日志）；按 `scope` 限定可见目录 |
| 分享链接 | 生成公开链接，可设密码、有效期、下载次数统计 |
| 审计日志 | 登录、上传、下载、改密、删除等操作留痕 |
| 扩展服务 | 可托管受管进程（如 Minecraft 服务端），带内存限制与命令下发（默认关闭） |
| 传输安全 | JWT + Argon2 口令哈希，令牌绑定 IP 与 UA，登录失败限速 |

## 与上游项目的差异

本项目是 [MertJSX/folderhost](https://github.com/MertJSX/folderhost)（GPL-3.0）的衍生版本，主要修改：

1. **界面全量中文化** — 覆盖 36 个组件、约 360 处文案，采用源码级替换（非运行时注入）。
   词典与替换脚本见 [`web/localize.py`](web/localize.py)，可重复执行以便跟随上游升级。
2. **补充中文文档** — 部署、内网穿透、安全审计三份文档见 [`docs/`](docs/)。
3. **配置示例加固** — `config.example.yml` 标注了所有必须修改的安全项。

未修改的部分：后端逻辑、数据库结构、API 接口、权限模型均与上游一致。
升级 upstream 时，`git pull` 会与汉化改动冲突，处理方式见 [`docs/deploy.md`](docs/deploy.md)。

## 快速开始

### 方式一：直接使用预编译二进制

从 Releases 下载压缩包，解压后：

```cmd
mkdir host
copy config.example.yml config.yml
:: 编辑 config.yml，改掉 admin.password
mycloudbox.exe
```

浏览器打开 `http://127.0.0.1:5000`。

> 目录下未附带预编译二进制时，请使用方式二自行构建。

### 方式二：源码编译

需要 **Go 1.25+** 与 **Node.js 20+**。

```bash
git clone https://gitee.com/yang_tao_code/mycloudbox.git
cd mycloudbox

# 1. 构建前端（产物会被 go:embed 打进二进制）
cd web && npm install && npm run build && cd ..

# 2. 构建后端
go build -trimpath -ldflags "-s -w -X main.Version=v1" -o mycloudbox.exe .
```

> 国内网络建议设置模块代理：`set GOPROXY=https://goproxy.cn,direct`

### 方式三：Docker

```bash
docker build -t mycloudbox:v1 .
docker run -d --name mycloudbox \
  -p 5000:5000 \
  -v mycloudbox_data:/app \
  --restart unless-stopped \
  mycloudbox:v1
```

首次启动会在工作目录生成 `config.yml` 与 `database.db`，按需修改后重启容器生效。

## 配置说明

配置文件为工作目录下的 `config.yml`（从 `config.example.yml` 复制而来）。关键项：

| 字段 | 说明 |
|---|---|
| `port` | 监听端口，默认 5000。被占用时自动顺延至 5001–6000 |
| `folder` | 文件存储根目录，相对工作目录。**必须事先创建** |
| `storage_limit` | 总容量上限，如 `"20 GB"` |
| `secret_jwt_key` | JWT 签名密钥，`"auto"` 表示自动生成 |
| `admin.password` | 管理员明文口令。**每次启动都会覆盖数据库中的口令** |
| `admin.scope` | 限定管理员可见目录，如 `/docs`；留空表示全部 |
| `recovery_bin` | 是否启用回收站 |
| `ssl.enabled` | 是否启用 HTTPS（自签或 Let's Encrypt） |

⚠️ **`admin.password` 的覆写机制**：程序每次启动都会执行 `UpdateAdmin()`，
用 `config.yml` 里的明文密码重新哈希并写库。
因此**在网页上修改管理员密码，重启后会失效**；要真正改密码必须改 `config.yml`。

## 部署为 Windows 服务

推荐用「计划任务」托管（比 `sc create` 更省事，且能开机自启、崩溃重启）：

```cmd
:: start-mycloudbox.cmd 内容：
::   @echo off
::   cd /d "%~dp0"
::   "%~dp0mycloudbox.exe"

schtasks /create /tn "mycloudbox" /tr "D:\mycloudbox\start-mycloudbox.cmd" /sc onstart /ru SYSTEM /rl HIGHEST /f
schtasks /run /tn "mycloudbox"
```

注意：程序所有路径都相对工作目录，**启动脚本里必须先 `cd` 到程序目录**，否则会找不到 `config.yml` 和 `host`。

详细步骤（防火墙、备份、升级、排错）见 [`docs/deploy.md`](docs/deploy.md)。

## 公网访问（内网穿透）

不想暴露公网 IP、也不想在路由器上做端口映射，推荐 **Cloudflare Tunnel**：
本机主动向外建立长连接，外部通过固定域名访问，防火墙无需开放任何入站端口。

配置步骤见 [`docs/tunnel.md`](docs/tunnel.md)。要点：

- 隧道传输协议建议用 `http2`（部分地区 QUIC/UDP 会被中断）
- 隧道回源地址填 `http://127.0.0.1:5000`
- **公网可达前务必先在 Cloudflare 侧加一层 Access 邮箱验证**

## 安全须知

本项目默认配置是**为内网使用**设计的，直接暴露公网有风险。上线前请逐条确认：

- [ ] 修改 `admin.password`，不要使用默认值
- [ ] 设置独立的 `secret_jwt_key`（或保留 `auto` 让程序生成）
- [ ] 收紧 `config.yml` 与 `database.db` 的文件权限（仅服务账户可读）
- [ ] 防火墙只放行内网网段，不要把 5000 端口直接映射到公网
- [ ] 保持 `services.yml` 中 `enable_services: false`（该功能可执行任意命令）
- [ ] 公网入口叠加一层身份网关（Cloudflare Access / 反向代理 Basic Auth / VPN）
- [ ] 定期备份 `database.db` + `host/` + `config.yml`

完整的安全审计（含已发现的中低危问题与缓解建议）见 [`docs/security-audit.md`](docs/security-audit.md)。

已知设计层面的注意点（属上游行为，非本项目引入）：

- 管理员口令以明文形式存于 `config.yml`
- `/api/raw` 对 SVG 使用 `image/svg+xml` 内联返回，存在存储型 XSS 风险
- WebSocket 鉴权不校验 IP/UA 指纹（HTTP 侧有校验）
- CORS 默认允许所有来源
- 分享链接密码校验无失败次数限制

## 常见问题

**Q：启动后端口不通、进程直接退出？**
`folder` 指定的目录不存在时，程序在统计目录大小时会直接 `return` 退出。先 `mkdir host`。

**Q：网页上改了管理员密码，重启就变回去了？**
设计如此，见[配置说明](#配置说明)中的覆写机制。

**Q：端口从 5000 变成 5001 了？**
5000 被占用，程序自动顺延。用 `netstat -ano | findstr :5000` 确认实际端口，或改 `config.yml` 固定。

**Q：公网访问很慢？**
Cloudflare 免费版在中国大陆无节点，流量会绕道境外（实测到美西边缘 RTT 250 ms 以上），
首字节 2 秒级属正常。要求低延迟需自建国内或香港中转（frp）。

**Q：升级上游后中文变回英文了？**
`git pull` 覆盖了汉化改动。重新执行 `python web/localize.py` 并重新构建即可。

## 许可证

本项目遵循 **GNU General Public License v3.0**，与上游一致。完整条款见 [LICENSE](LICENSE)。

这意味着：你可以自由使用、修改、分发，但**衍生作品也必须以 GPL-3.0 开源**，并保留原始版权声明。

### 上游归属

- 原始项目：[MertJSX/folderhost](https://github.com/MertJSX/folderhost)
- 原作者：MertJSX
- 上游版本：v26.11.0（commit `66a694a`，2026-11-01）
- 官方网站：<https://folderhost.org>
- 上游原始 README 存档：[docs/upstream-readme.md](docs/upstream-readme.md)

本仓库对其进行了中文化与文档补充，未改变原有授权方式。

## 致谢

感谢 [MertJSX](https://github.com/MertJSX) 提供这样一个轻量、干净的自托管文件管理方案。