26.9（安全审计修复版）

Go 1.27.1 (Gin+GORM) + Vue 3 文件快传服务： - 安全审计全部修复（docs/security-audit-2026-09-05.md）： bcrypt 密码哈希与自动升级、presign 直传服务端大小/内容校验、全局请求体上限、依赖升级（govulncheck 0 命中）、janitor 后台清理、管理端审计动作落库、/admin CORS 收紧、通知内容白名单净化、会话默认 7 天、限流缓存故障降级、robots.txt 端点等 - 前端：取件链接复制修复（不再重复拼接提取码）、markdown 净化器加固 - Redis 支持库号（FCB_REDIS_DB / redis://…/db URL） - 文档：docs/api/* 与 openapi.yaml 同步最新行为（robots.txt、提码 5 位起、chunk 32MiB 上限、admin 审计动作等）验证：gofmt/go vet/go test 全绿；二进制端到端冒烟通过
2026-09-05 04:22:41 +08:00
commit 7f060dd0e4
173 changed files with 32455 additions and 0 deletions
@@ -0,0 +1,60 @@
+# ===== FileCodeBox 部署环境变量示例 =====
+# 复制为 .env 后按需修改；所有变量均有默认值。
+
+# ---- 站点 ----
+WEB_PORT=8466
+
+# ---- 数据库（需求 ⑧）----
+# 默认 SQLite：零依赖，无需任何下方 Postgres 变量（数据落 serverdata 卷 /app/data/filecodebox.db）
+FCB_DB_DRIVER=sqlite
+FCB_DB_DSN=
+# Postgres 模式（可选）：先 `docker compose --profile postgres up -d --build`，再改为：
+# FCB_DB_DRIVER=postgres
+# FCB_DB_DSN=postgres://filecodebox:filecodebox@postgres:5432/filecodebox?sslmode=disable
+
+# ---- Postgres（仅 --profile postgres 时使用；生产务必修改默认口令并启用 TLS）----
+POSTGRES_USER=filecodebox
+POSTGRES_PASSWORD=filecodebox
+POSTGRES_DB=filecodebox
+
+# ---- 存储引擎切换：local | s3 | webdav ----
+FCB_STORAGE_ENGINE=local
+
+# ---- 可信代理（生产必读，安全审计 L10）----
+# 反代（nginx/caddy 等）后必须设为代理 IP/CIDR（逗号分隔），
+# 否则限流按代理 IP 计数（全体用户共享一个限流桶）且审计 IP 失真。
+# 示例：FCB_TRUSTED_PROXIES=172.18.0.0/16,10.0.0.5
+FCB_TRUSTED_PROXIES=
+
+# ---- 管理员自动初始化（可选，安全审计 L1）----
+# 设置后服务首次启动即完成管理员初始化（≥8 位），消除 /setup 被抢占窗口；
+# 初始化完成后建议移除该变量。留空则走 /setup 网页向导。
+# FCB_ADMIN_PASSWORD=
+
+# ---- 管理员会话有效期（秒，默认 7 天，可调 1~365 整天）----
+# FCB_ADMIN_SESSION_EXPIRE=604800
+
+# ---- 本地引擎 ----
+# 容器内固定 /app/data；compose 已挂载 serverdata 卷
+# FCB_LOCAL_STORAGE_PATH=/app/data
+
+# ---- Redis（可选增强；留空=内存降级；启用服务用 --profile redis）----
+# FCB_REDIS_ADDR=redis:6379
+# Redis 逻辑库号 0-15（默认 0）；地址为 redis://…/N URL 形式时以 URL 内库号优先
+# FCB_REDIS_DB=0
+
+# ---- S3 引擎（FCB_STORAGE_ENGINE=s3 时必填 bucket/access/secret；服务用 --profile minio）----
+# 注意：minioadmin/minioadmin 仅为本机冒烟默认值，对外部署必须修改
+# （并在 compose 中删除 minio 的 ports 发布或仅绑定 127.0.0.1）
+FCB_S3_ENDPOINT_URL=http://minio:9000
+FCB_S3_BUCKET_NAME=filecodebox
+FCB_S3_ACCESS_KEY_ID=minioadmin
+FCB_S3_SECRET_ACCESS_KEY=minioadmin
+FCB_S3_REGION_NAME=us-east-1
+# FCB_S3_ADDRESSING_STYLE=auto
+
+# ---- WebDAV 引擎（FCB_STORAGE_ENGINE=webdav 时必填 url；服务用 --profile webdav）----
+FCB_WEBDAV_URL=http://webdav:5000
+FCB_WEBDAV_USERNAME=admin
+FCB_WEBDAV_PASSWORD=admin123
+FCB_WEBDAV_ROOT_PATH=filebox_storage
@@ -0,0 +1,45 @@
+# 文件快传 Go 版多阶段构建：
+# 1) node:20-alpine 构建 Vue 前端产物（web/dist）
+# 2) golang:1.27.1-alpine 编译 server（go:embed 前端产物，缓存指向 /tmp 避免写权限问题）
+# 3) 最小运行时镜像：server 二进制 + web/dist 静态产物
+FROM node:20-alpine AS frontend
+WORKDIR /build
+COPY web/package.json web/package-lock.json* ./
+RUN npm ci || npm install
+COPY web/ ./
+RUN npm run build
+
+FROM golang:1.27.1-alpine AS backend
+WORKDIR /build
+# GOPROXY：默认走 goproxy.cn（proxy.golang.org 的 GCS 后端在本环境网络下 EOF/超时），direct 兜底
+ENV CGO_ENABLED=0 GOSUMDB=off GOPROXY=https://goproxy.cn,direct GOCACHE=/tmp/.gocache GOMODCACHE=/tmp/.gomodcache
+# 先拷贝 go.mod/go.sum 利用层缓存
+COPY server/go.mod server/go.sum ./
+RUN go mod download
+COPY server/ ./
+# 前端产物嵌入（go:embed 目标目录 server/web/dist）：
+# 优先用宿主预构建产物 web-embed/（构建前由 `cp -a web/dist web-embed/` 维护，
+# 保证 embed 与前端最新修正一致）；为空/缺失时回退跨阶段 COPY（CI 兜底）
+COPY --from=frontend /build/dist ./frontend-dist
+COPY web-embed/ ./web-embed/
+RUN if [ -f web-embed/index.html ]; then \
+        rm -rf web/dist && cp -a web-embed/. web/dist/; \
+    else \
+        rm -rf web/dist && cp -a frontend-dist/. web/dist/; \
+    fi \
+ && rm -rf web-embed frontend-dist
+RUN go build -trimpath -ldflags "-s -w" -o /out/server ./cmd/server
+
+FROM alpine:3.20
+# curl 供容器健康检查使用
+RUN apk add --no-cache ca-certificates tzdata curl && adduser -D -u 10001 fcb
+WORKDIR /app
+COPY --from=backend /out/server /app/server
+# dist 随镜像分发（服务端已 go:embed，磁盘副本供运维检查/替换）
+COPY --from=backend /build/web/dist /app/web/dist
+RUN mkdir -p /app/data && chown -R fcb:fcb /app
+USER fcb
+ENV FCB_LISTEN=:8466
+EXPOSE 8466
+VOLUME ["/app/data"]
+ENTRYPOINT ["/app/server"]
@@ -0,0 +1,135 @@
+# 文件快传 部署编排（deploy/）
+
+Go 1.27.1（Gin + GORM）+ Vue 3 重写版（v3.1）的容器化部署。数据库**默认 SQLite，零外部依赖**
+（modernc.org/sqlite 纯 Go 驱动，无需 Postgres），可选切换 Postgres（`--profile postgres`）；
+Redis 为可选增强（`--profile redis`），未配置 `FCB_REDIS_ADDR` 时服务端自动降级为进程内存缓存。
+
+> v3.1 功能提示：管理后台可设「站点对外域名」（内网部署生成公网分享链接）、
+> 分享时支持自定义提取码（4-8 位字母数字）；这些均为运行时配置，无需改部署。
+
+## compose 服务与 profile 一览
+
+| 启动方式 | 服务 | 说明 |
+|---|---|---|
+| `docker compose up -d --build` | server | **默认：SQLite 零依赖**，仅启动一个容器 |
+| `--profile postgres` | postgres | 可选：Postgres 数据库（数据落 `pgdata` 卷） |
+| `--profile redis` | redis | 可选：缓存增强（未配置自动内存降级） |
+| `--profile minio` | minio + minio-init | 可选：S3 引擎冒烟（minio-init 用 mc 自动建桶） |
+| `--profile webdav` | webdav | 可选：WebDAV 引擎冒烟（dufs） |
+
+## 数据库双路径（需求 ⑧）
+
+### 路径 ①：默认 SQLite（零依赖，推荐）
+
+无需 postgres profile，也无需任何数据库环境变量：
+
+```bash
+cd deploy
+cp .env.example .env            # 保持 FCB_DB_DRIVER=sqlite、FCB_DB_DSN 留空（默认值即可）
+docker compose up -d --build
+# 打开 http://localhost:8466（.env 可用 WEB_PORT 改端口）→ 自动跳转 /setup 完成初始化
+```
+
+- 数据落 **`serverdata` 卷**：容器内 `/app/data/filecodebox.db`（WAL 模式，父目录自动创建）。
+- `.env` 中 Postgres 段变量（`POSTGRES_USER/PASSWORD/DB`）在此模式下不生效，无需修改。
+
+### 路径 ②：Postgres 模式（可选）
+
+1. 编辑 `.env`：
+
+   ```dotenv
+   FCB_DB_DRIVER=postgres
+   FCB_DB_DSN=postgres://filecodebox:filecodebox@postgres:5432/filecodebox?sslmode=disable
+   ```
+
+2. 带 postgres profile 启动（server 会等 postgres 健康检查通过后再启动）：
+
+   ```bash
+   docker compose --profile postgres up -d --build
+   ```
+
+- compose 将 `.env` 的 `FCB_DB_DRIVER/FCB_DB_DSN` 透传给 server 容器；DSN 主机必须为 compose
+  服务名 `postgres`，凭据与 `POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB` 一致。
+- Postgres 数据落 `pgdata` 卷；首次启动自动执行迁移（AutoMigrate）。
+
+> 注意：设置 `FCB_DB_DRIVER=postgres` 后务必带 `--profile postgres` 启动，否则 postgres
+> 服务不会创建，server 将因连不上数据库而反复重启。
+
+服务未初始化时（两种数据库模式行为一致）除 `/setup` 与 `/api/v1/health` 外一律返回 428，
+浏览器打开站点按向导设置管理员密码。
+
+## 存储引擎切换（本地 / S3 / WebDAV）
+
+修改 `.env` 中 `FCB_STORAGE_ENGINE` 并带对应 profile 启动：
+
+```bash
+# S3 引擎（MinIO 冒烟）
+docker compose --profile minio up -d --build   # .env: FCB_STORAGE_ENGINE=s3
+#   minio-init 一次性任务自动建桶（mc mb filecodebox）
+
+# WebDAV 引擎（dufs 冒烟，Basic 认证 admin/admin123@/:rw）
+docker compose --profile webdav up -d --build  # .env: FCB_STORAGE_ENGINE=webdav
+```
+
+> **v3 起支持运行时热切换**：也可不改 `.env`，直接在管理后台「系统设置 → 存储引擎」
+> 三选并保存引擎参数后点切换（健康检查通过才生效，失败保持原引擎），或调用
+> `POST /admin/storage/switch`——均无需重启容器。`.env` 的 `FCB_STORAGE_ENGINE`
+> 仅作为首次启动（KV 为空时）的默认引擎。
+
+## Redis 缓存增强（可选）
+
+Redis 不是必需服务：`--profile redis` 启动**且** `.env` 设 `FCB_REDIS_ADDR=redis:6379` 才接入；
+未配置（或未启用该 profile）时服务端**自动降级为进程内存缓存**，单实例部署功能完全可用，
+多实例部署或需要重启保活计数/会话场景时建议启用。
+
+```bash
+docker compose --profile redis up -d --build   # .env: FCB_REDIS_ADDR=redis:6379
+```
+
+## 文件说明
+
+| 文件 | 说明 |
+|---|---|
+| `Dockerfile` | 三阶段构建：node 构建 web/dist → go 编译（go:embed 前端产物）→ alpine 运行镜像 |
+| `docker-compose.yml` | server + 四个可选 profile：postgres / redis / minio（含 mc 建桶）/ webdav |
+| `.env.example` | 全量环境变量：`FCB_DB_DRIVER` 双路径、三引擎切换、`WEB_PORT`、可信代理 |
+
+## 健康检查与验证
+
+端口由 `.env` 的 `WEB_PORT`（默认 `8466`）映射到容器内 `8466`：
+
+```bash
+curl http://localhost:8466/api/v1/health    # {"code":200,"data":{"status":"ok",...}}
+curl -I http://localhost:8466/               # 200，前端 SPA
+curl -I http://localhost:8466/docs           # 200（SPA 回退）
+```
+
+## 注意事项
+
+- **数据持久化**：SQLite 数据库与本地引擎文件都在 `serverdata` 卷（容器内 `/app/data`）；
+  Postgres 模式数据在 `pgdata` 卷；redis/minio/webdav 数据各在独立卷。
+  切换数据库驱动不会自动迁移既有数据（SQLite 文件与 Postgres 库互相独立）。
+- **非 root 运行**：容器以 uid 10001 运行。
+- **日志**：`docker compose logs -f server`。
+- **CORS**：同源部署无需额外配置；`/admin/*` 已收紧——仅同源或 `site_domain` 白名单可跨域调用，
+  其余跨域由浏览器拦截；公开接口维持 `*`（Bearer 认证，无 Cookie CSRF 面）。
+
+## 安全清单（生产部署必读）
+
+安全审计（`docs/security-audit-2026-09-05.md`）后的部署要求：
+
+1. **反向代理必须配置可信代理**：`.env` 设 `FCB_TRUSTED_PROXIES=<代理IP/CIDR>`（逗号分隔）。
+   否则限流按代理 IP 计数（全体用户共享一个限流桶、互相误伤），审计日志 IP 失真；
+   也不可把不受信地址加进来——那会允许伪造 `X-Forwarded-For` 绕过限流。
+2. **部署后立即初始化管理员**：打开站点完成 `/setup`（设置 ≥8 位密码），
+   或在 `.env` 设 `FCB_ADMIN_PASSWORD`（≥8 位）让服务启动即自动初始化，
+   消除「公网上被抢先访问 /setup 接管」的窗口。初始化完成后建议从 `.env` 移除该变量。
+3. **修改组件默认凭据**：minio（`minioadmin/minioadmin`）、webdav（`admin/admin123`）、
+   Postgres（`filecodebox/filecodebox`）默认凭据仅限本机冒烟；对外部署必须修改，
+   且不建议把 9000/9001/5005 端口发布到公网（compose 中删除对应 `ports` 或仅绑 127.0.0.1）。
+4. **Postgres 建议启用 TLS**：默认示例 DSN 为 `sslmode=disable`，生产请改为
+   `sslmode=require` 及以上。
+5. **管理员会话默认 7 天**（可在管理端调 1~365 天）；修改管理员密码会使全部旧 token 失效。
+6. **上传/登录限流**依赖内存或 Redis 缓存；Redis 故障时自动降级为进程内限流（单实例语义）。
+7. **后台清理任务**：服务内置每 10 分钟的过期容量预留 / 超时上传会话 / 直传残留对象清理，
+   无需额外 cron。
@@ -0,0 +1,144 @@
+# 文件快传 Go 版部署编排（v2，需求 ⑧）：
+#   docker compose up -d --build                  # 默认：SQLite 零依赖（仅 server 容器）
+#   docker compose --profile postgres up -d --build   # 可选：Postgres 模式（自动注入 FCB_DB_DSN）
+#   docker compose --profile redis up -d          # 可选：Redis 缓存增强
+#   docker compose --profile minio up -d          # 可选：S3 引擎冒烟（FCB_STORAGE_ENGINE=s3）
+#   docker compose --profile webdav up -d         # 可选：WebDAV 引擎冒烟（FCB_STORAGE_ENGINE=webdav）
+#
+# 数据库默认 SQLite（modernc.org/sqlite 纯 Go 驱动，数据落 serverdata 卷 /app/data/filecodebox.db）；
+# postgres 为可选 profile 服务，启用时 server 经 FCB_DB_DRIVER/FCB_DB_DSN 自动接入；
+# Redis 同为可选，未配置时服务端内存降级。
+name: filecodebox
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    # 可选服务（需求 ⑧）：默认 SQLite 模式不会启动 postgres；
+    # 需要时 docker compose --profile postgres up -d --build
+    profiles: ["postgres"]
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-filecodebox}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-filecodebox}
+      POSTGRES_DB: ${POSTGRES_DB:-filecodebox}
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-filecodebox}"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  server:
+    build:
+      context: ..
+      dockerfile: deploy/Dockerfile
+    restart: unless-stopped
+    depends_on:
+      # postgres 为可选 profile 服务：--profile postgres 启用时等它健康，
+      # 默认 SQLite 模式不启用该 profile，不阻塞启动
+      postgres:
+        condition: service_healthy
+        required: false
+      # redis 为可选 profile 服务：启用时等它健康，未启用不阻塞启动
+      redis:
+        condition: service_healthy
+        required: false
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://127.0.0.1:8466/api/v1/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 30
+      start_period: 5s
+    environment:
+      # 需求 ⑧：数据库驱动 sqlite（默认，零依赖）| postgres（需 --profile postgres）
+      # 默认 SQLite：DSN 留空 → 数据库文件落 /app/data/filecodebox.db（serverdata 卷）
+      # postgres 模式：在 .env 设 FCB_DB_DRIVER=postgres 与 FCB_DB_DSN（模板见 deploy/.env.example）
+      FCB_DB_DRIVER: ${FCB_DB_DRIVER:-sqlite}
+      FCB_DB_DSN: ${FCB_DB_DSN:-}
+      FCB_LISTEN: ":8466"
+      FCB_STORAGE_ENGINE: ${FCB_STORAGE_ENGINE:-local}
+      # Redis 可选增强：.env 设 FCB_REDIS_ADDR=redis:6379 且 --profile redis 启用时接入；
+      # 默认留空=内存缓存（需求 ⑧）
+      FCB_REDIS_ADDR: ${FCB_REDIS_ADDR:-}
+      FCB_REDIS_DB: ${FCB_REDIS_DB:-0}
+      FCB_TRUSTED_PROXIES: ${FCB_TRUSTED_PROXIES:-}
+      # 本地引擎根目录（容器内）
+      FCB_LOCAL_STORAGE_PATH: /app/data
+      # S3 引擎（MinIO profile）
+      FCB_S3_ENDPOINT_URL: ${FCB_S3_ENDPOINT_URL:-}
+      FCB_S3_BUCKET_NAME: ${FCB_S3_BUCKET_NAME:-filecodebox}
+      FCB_S3_ACCESS_KEY_ID: ${FCB_S3_ACCESS_KEY_ID:-minioadmin}
+      FCB_S3_SECRET_ACCESS_KEY: ${FCB_S3_SECRET_ACCESS_KEY:-minioadmin}
+      FCB_S3_REGION_NAME: ${FCB_S3_REGION_NAME:-us-east-1}
+      # WebDAV 引擎（dufs profile）
+      FCB_WEBDAV_URL: ${FCB_WEBDAV_URL:-}
+      FCB_WEBDAV_USERNAME: ${FCB_WEBDAV_USERNAME:-admin}
+      FCB_WEBDAV_PASSWORD: ${FCB_WEBDAV_PASSWORD:-admin123}
+      FCB_WEBDAV_ROOT_PATH: ${FCB_WEBDAV_ROOT_PATH:-filebox_storage}
+    ports:
+      - "${WEB_PORT:-8466}:8466"
+    volumes:
+      - serverdata:/app/data
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    profiles: ["redis"]
+    volumes:
+      - redisdata:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  minio:
+    image: minio/minio:latest
+    restart: unless-stopped
+    profiles: ["minio"]
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${FCB_S3_ACCESS_KEY_ID:-minioadmin}
+      MINIO_ROOT_PASSWORD: ${FCB_S3_SECRET_ACCESS_KEY:-minioadmin}
+    ports:
+      - "${MINIO_API_PORT:-9000}:9000"
+      - "${MINIO_CONSOLE_PORT:-9001}:9001"
+    volumes:
+      - miniodata:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  # MinIO 建桶初始化（mc；一次性任务）
+  minio-init:
+    image: minio/mc:latest
+    profiles: ["minio"]
+    depends_on:
+      minio:
+        condition: service_healthy
+    entrypoint: >
+      /bin/sh -c "
+      mc alias set local http://minio:9000 ${FCB_S3_ACCESS_KEY_ID:-minioadmin} ${FCB_S3_SECRET_ACCESS_KEY:-minioadmin} &&
+      mc mb --ignore-existing local/${FCB_S3_BUCKET_NAME:-filecodebox} &&
+      echo 'MinIO 桶已就绪'"
+
+  # WebDAV 冒烟服务器（dufs，简单读写 + Basic 认证）
+  webdav:
+    image: sigoden/dufs:latest
+    restart: unless-stopped
+    profiles: ["webdav"]
+    command: /data -A -a admin:admin123@/:rw
+    ports:
+      - "${WEBDAV_PORT:-5005}:5000"
+    volumes:
+      - webdavdata:/data
+
+volumes:
+  pgdata:
+  redisdata:
+  miniodata:
+  webdavdata:
+  serverdata: