196 lines
8.0 KiB
Markdown
196 lines
8.0 KiB
Markdown
# CHFS-NG
|
||
|
||
CHFS-NG 是基于 CHFS 思路重构的轻量级、自托管 Web 文件管理器。它保留单二进制、低资源占用和 WebDAV 的特点，同时提供现代化文件管理 UI、动态用户、个人私有盘以及移动端友好操作。
|
||
|
||
## 特性
|
||
- 单 Go 二进制，前端资源内嵌，无外部前端依赖
|
||
- 现代文件管理 UI：列表/网格、排序、多选、拖拽、批量复制/移动/删除、搜索
|
||
- 图片 Gallery、音视频预览、视频倍速/PiP、音频迷你播放器
|
||
- 在线文本/代码编辑，支持 Ctrl/Cmd+S 保存
|
||
- 上传队列、进度、取消与重试，支持文件夹拖拽上传
|
||
- 动态用户管理与独立个人私有目录
|
||
- 多根目录与目录级读写/删除权限
|
||
- 完善的权限体系：支持访客/只读/读写/删除动态权限控制及安全防御
|
||
- 缩略图本地缓存与流式预览优化，低内存开销
|
||
- 桌面端（1080P/2K/4K）与移动端自适应布局，视觉规整与操作闭环
|
||
- 分享、二维码移动传输、WebDAV
|
||
- 健康检查：/healthz
|
||
- 资源耗尽防护：上传、ZIP 打包、搜索与缩略图均有默认资源上限
|
||
- 缩略图先通过 DecodeConfig 校验像素面积，再执行完整解码，避免声明尺寸型图片导致内存耗尽
|
||
- 上传入口在 multipart 解析前使用 MaxBytesReader 限制请求体总量
|
||
- 反向代理场景支持可信代理配置，仅对可信来源解析 X-Forwarded-For / X-Real-IP
|
||
- 构建产物使用 -s -w，适合轻量 NAS
|
||
|
||
## 快速开始
|
||
|
||
### 直接运行
|
||
```bash
|
||
make build
|
||
./bin/chfs-ng -path /srv/files -port 8080
|
||
```
|
||
访问 http://127.0.0.1:8080/。
|
||
|
||
### Docker Compose
|
||
在仓库根目录执行：
|
||
```bash
|
||
mkdir -p deploy/data
|
||
cd deploy
|
||
docker compose up -d --build
|
||
```
|
||
默认宿主机端口为 8080，数据位于 deploy/data。可用 CHFS_PORT=9090 docker compose up -d --build 修改端口。
|
||
|
||
## 启动参数
|
||
| 参数 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| -path | /data | 共享根目录；可用 | 分隔多个根目录 |
|
||
| -port | 80 | HTTP 监听端口 |
|
||
| -file | 空 | 配置文件路径 |
|
||
| -allow | 空 | 允许访问的 IPv4 地址 |
|
||
| -rule | 空 | 访问规则，可重复指定 |
|
||
| -version | false | 输出版本后退出 |
|
||
|
||
示例：
|
||
```bash
|
||
./bin/chfs-ng -path /srv/files -port 8080 -file /etc/chfs-ng/config.ini
|
||
```
|
||
显式指定的命令行参数会覆盖配置文件中的对应值。
|
||
|
||
## 动态用户与个人私有盘
|
||
|
||
CHFS-NG 支持运行时管理动态用户。管理员可以在 Web UI 的“用户管理”中创建、启用/禁用、修改密码和删除用户，并为用户设置个人空间。
|
||
|
||
默认个人空间根目录为：
|
||
```
|
||
users/
|
||
├── alice/
|
||
├── bob/
|
||
└── ...
|
||
```
|
||
|
||
用户登录后，“我的空间”指向自己的个人目录。个人目录由系统自动创建，并默认具有该用户的读、写、删除权限；其他普通用户不会因为登录而自动获得这些目录的访问权。
|
||
|
||
个人空间根目录可通过配置项 UserHome 指定。动态用户数据默认持久化到操作系统用户配置目录下的 chfs-ng/users.json；Docker 部署时，建议把用户文件配置到持久化的 /data 下。
|
||
|
||
管理员账号可以通过配置文件提供，例如：
|
||
```ini
|
||
[account]
|
||
username = admin
|
||
password = change-me
|
||
role = admin
|
||
```
|
||
实际配置字段以当前版本配置解析器支持的格式为准。
|
||
|
||
## WebDAV
|
||
|
||
WebDAV 地址：
|
||
```
|
||
http://HOST:PORT/webdav
|
||
```
|
||
|
||
### Windows
|
||
“此电脑” → “映射网络驱动器”，输入 http://HOST:PORT/webdav，使用 CHFS-NG 用户名和密码登录。生产环境建议通过 HTTPS 暴露。
|
||
|
||
### macOS
|
||
Finder → “前往” → “连接服务器”，输入：
|
||
```
|
||
http(s)://HOST:PORT/webdav
|
||
```
|
||
|
||
### Linux
|
||
桌面文件管理器选择“连接到服务器”，GNOME Files 可使用：
|
||
```
|
||
dav://HOST:PORT/webdav
|
||
davs://HOST:PORT/webdav
|
||
```
|
||
命令行可使用支持 WebDAV 的客户端，例如 cadaver。
|
||
|
||
WebDAV 与 Web UI 使用同一套用户权限模型。多根目录模式下保持根目录隔离，不允许跨虚拟根目录复制或移动。
|
||
|
||
## 交叉编译
|
||
```bash
|
||
make build-linux-amd64
|
||
make build-linux-arm64
|
||
make build-linux-armv7
|
||
make build-linux
|
||
```
|
||
输出：
|
||
```
|
||
bin/chfs-ng-linux-amd64
|
||
bin/chfs-ng-linux-arm64
|
||
bin/chfs-ng-linux-armv7
|
||
```
|
||
所有目标均使用 CGO_ENABLED=0、-trimpath 和 -ldflags "-s -w"，不依赖目标机器上的 Go 环境。
|
||
|
||
## 开发与验证
|
||
```bash
|
||
make test
|
||
make race
|
||
make vet
|
||
make check
|
||
```
|
||
版本号默认来自 git describe --tags --always --dirty，也可以：
|
||
```bash
|
||
make build VERSION=v1.0.0
|
||
./bin/chfs-ng -version
|
||
```
|
||
|
||
## Docker
|
||
采用 Go Alpine 多阶段构建：builder 只负责编译，runtime 仅保留 CHFS-NG、CA 证书和时区数据，并提供容器健康检查。
|
||
|
||
```bash
|
||
docker build --build-arg VERSION=v1.0.0 -t chfs-ng:v1.0.0 .
|
||
docker run -d --name chfs-ng --restart unless-stopped -p 8080:80 -v /srv/chfs:/data chfs-ng:v1.0.0
|
||
```
|
||
|
||
最终镜像目标控制在 15 MB 以内；实际大小会随 Go/Alpine 版本变化。
|
||
|
||
## 数据与安全
|
||
- /data 为推荐持久化目录
|
||
- 生产环境建议使用 HTTPS 反向代理
|
||
- 不要使用弱管理员密码
|
||
- 动态用户数据库需要与数据目录一起备份
|
||
- 公开部署时建议配合防火墙/反向代理
|
||
- WebDAV 优先使用 HTTPS
|
||
|
||
### 默认资源限制
|
||
|
||
以下限制默认启用，可通过配置文件调整；设置为 `0` 表示不启用对应限制。
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
| --- | ---: | --- |
|
||
| `thumbnail-max-size` | 32 MiB | 单个缩略图源文件最大大小 |
|
||
| `thumbnail-max-pixels` | 40,000,000 | 缩略图源图片最大像素面积 |
|
||
| `zip-max-size` | 2 GiB | ZIP 打包源文件总大小上限 |
|
||
| `zip-max-files` | 5000 | 单次 ZIP 最大文件数 |
|
||
| `upload-max-size` | 2 GiB | 单个上传文件最大大小 |
|
||
| `upload-max-total-size` | 4 GiB | 单次上传请求总大小上限 |
|
||
| `upload-max-files` | 100 | 单次上传最大文件数 |
|
||
| `search-max-results` | 500 | 单次搜索最大返回结果数；超过后标记 `truncated` |
|
||
| `trusted-proxies` | 空 | 可信反向代理地址；仅可信代理的请求会使用 X-Forwarded-For / X-Real-IP |
|
||
|
||
上传请求的总大小限制会在 multipart 解析之前生效；缩略图则先读取图片配置头并检查尺寸，再进行完整图片解码。
|
||
|
||
生产环境如果使用反向代理，应显式配置 `trusted-proxies`，避免客户端伪造转发头影响 IP 记录或 IP Allow 规则。
|
||
|
||
## 更新日志
|
||
|
||
### 2026-10-03
|
||
- **安全审计整改**：`/chfs/exist` 强制执行读取权限检查。
|
||
- **资源耗尽防护**：增加缩略图文件大小/像素面积、ZIP 文件数/原始文件大小、上传文件数/单文件大小/总请求大小以及搜索结果上限。
|
||
- **缩略图 OOM 防护**：使用 `image.DecodeConfig` 在完整 Decode 前校验声明尺寸，阻断超大尺寸图片解压炸弹。
|
||
- **上传请求体防护**：在 `ParseMultipartForm` 前使用 `http.MaxBytesReader` 限制请求体，避免超大 multipart 请求先被 spool 到临时文件。
|
||
- **回收站清理**：系统 Trash 增加默认 30 天自动清理。
|
||
- **可信代理**：增加 `trusted-proxies` 配置，仅信任配置范围内的代理转发真实客户端 IP。
|
||
- **密码安全**：新密码使用 bcrypt，同时兼容已有 SHA-256 密码平滑迁移。
|
||
- **生产部署**：当前生产环境采用二进制 + systemd 部署；Docker 仍作为独立部署方式提供。
|
||
|
||
### 2026-09-23
|
||
- **前端交互与弹窗修复**：修复 `ask()` 弹窗中事件监听与回车提交逻辑，支持新建文件夹/新建文本顺畅操作。
|
||
- **桌面端大屏视口适配**：放宽主容器宽度至 1600px 并动态对齐顶部导航栏边距，补全表格操作列，消除 PC 端右侧大屏留白断层。
|
||
- **移动端与跨浏览器表格对齐**：固化列表各列宽度（`table-layout: fixed`），优化移动端触屏操作栏显示。
|
||
- **访客权限与交互收紧**：统一未登录访客的多选及操作限制，修复危险操作按钮层叠样式。
|
||
- **缩略图缓存机制**：引入生成缓存与内存保护机制，加快大图加载并降低宿主机内存消耗。
|
||
|
||
## License
|
||
本项目许可证以仓库中的 LICENSE 文件为准。
|