From 4dafcff680cb5848f07ef7afdf84b2886b940e6b Mon Sep 17 00:00:00 2001 From: kory Date: Sat, 3 Oct 2026 02:30:21 +0800 Subject: [PATCH] docs: document security limits and deployment --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index 3e16fa4..f4a60eb 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ CHFS-NG 是基于 CHFS 思路重构的轻量级、自托管 Web 文件管理器 - 桌面端（1080P/2K/4K）与移动端自适应布局，视觉规整与操作闭环 - 分享、二维码移动传输、WebDAV - 健康检查：/healthz +- 资源耗尽防护：上传、ZIP 打包、搜索与缩略图均有默认资源上限 +- 缩略图先通过 DecodeConfig 校验像素面积，再执行完整解码，避免声明尺寸型图片导致内存耗尽 +- 上传入口在 multipart 解析前使用 MaxBytesReader 限制请求体总量 +- 反向代理场景支持可信代理配置，仅对可信来源解析 X-Forwarded-For / X-Real-IP - 构建产物使用 -s -w，适合轻量 NAS ## 快速开始 @@ -148,8 +152,38 @@ docker run -d --name chfs-ng --restart unless-stopped -p 8080:80 -v /srv/chfs:/d - 公开部署时建议配合防火墙/反向代理 - 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 端右侧大屏留白断层。