Chibisafe v6.7.0 Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上，用官方三服务 Compose 组合（前端 + 后端 + Caddy 入口）从零部署 Chibisafe v6.7.0，完成首次登录、修改默认密码、文件上传（单文件与分块）、直链下载与短链分享的全链路验证。全部命令与回显均在 2026-10-30 于 Ubuntu 22.04 实机实测通过。

一、环境信息

本文实测所用的服务器环境与软件版本如下（查询/实测日期 2026-10-30）：

操作系统：Ubuntu 22.04（x86_64，内核 7.0.0-38-generic）
Chibisafe 版本：v6.7.0（官方最新稳定版，来源 GitHub Releases；部署后经 GET /api/version 实测返回 {"version":"6.7.0"} 交叉确认）
Docker：24.x 与 Docker Compose v2（docker compose 子命令形态）
Web 对外端口：8152（映射到栈内 Caddy 的 80 端口；官方默认示例为 24424，可按需改映射）
官方镜像：chibisafe/chibisafe:latest（前端，约 368MB）、chibisafe/chibisafe-server:latest（后端，约 1.4GB）、caddy:2-alpine（入口，约 93MB）
数据目录：database/、uploads/、logs/（部署目录下的三个 bind mount 子目录）
默认管理员账号：admin / admin（首次登录后立即改密）
相关背景与选型对比见《Chibisafe 介绍与选型指南》

二、镜像选型说明

Chibisafe v6 的官方 Docker 形态由三个镜像组成，三者缺一不可（来源：官方文档 https://chibisafe.app/docs/installation/running-with-docker ，查询日期 2026-10-30）：

镜像	角色	监听端口	说明
`chibisafe/chibisafe:latest`	Web 前端（Next.js）	8001（栈内）	渲染管理界面与上传页，通过 `BASE_API_URL` 指向后端
`chibisafe/chibisafe-server:latest`	API 后端（Fastify/Node）	8000（栈内）	鉴权、分块合并、元数据（内嵌 SQLite）、缩略图、统计
`caddy:2-alpine`	统一入口（Caddy）	80（映射为宿主 8152）	把前端与后端「合并成 1 个对外端口」，并直接以文件服务器角色吐出 `uploads/` 目录里的文件

官方镜像 tag 沿用 latest（稳定版）与 dev（master 分支构建）两条流（来源：官方文档，查询日期 2026-10-30）。latest 在 2026-10-30 实查对应 v6.7.0。

💡 技术拓展：为什么栈内必须保留 Caddy，而不能用自己的 Nginx 直接反代前端？——v6 把「页面、API、文件下载」拆在两个服务上：/api/* 与 /docs* 要转发给后端 8000，其余路径给前端 8001，而文件 GET 请求又要求 Caddy 以静态文件方式直接读 uploads/ 目录（不经过应用进程），并且官方 Caddyfile 对上传文件响应注入 CSP sandbox 等安全头（来源：仓库 README「Uploaded file security」节）。官方明确以 danger 级别提示：即使宿主机已有 Nginx Proxy Manager 或 Caddy，栈内 Caddy 也必须保留，否则合并路由会断裂（来源：官方文档 danger 提示框，查询日期 2026-10-30）。宿主机的反代（Nginx/Caddy）统一指向 8152 即可，二者不冲突。

三、前置条件

一台 x86_64 的 Ubuntu 22.04 服务器，具备 sudo 权限；
已安装 Docker Engine 与 Docker Compose v2（docker compose version 能输出版本号）；
对外服务端口未被占用（本文取 8152，可用 ss -ltn | grep 8152 自查，无输出即空闲）；
磁盘剩余空间：官方三镜像合计解压后约 2GB，另需为 uploads/ 预留业务容量；
服务器可访问 Docker Hub（国内网络拉取官方镜像较慢时，可为 Docker 守护进程配置代理，本文实测时后端镜像 1.4GB 拉取耗时约 25 分钟，属正常范围）。

确认环境：

docker compose version

实测回显：

Docker Compose version v2.29.7

ss -ltn | grep 8152 || echo "8152 free"

实测回显：

8152 free

四、部署步骤

本节从空目录开始，创建目录结构、编写两个配置文件、启动服务栈、完成首次登录改密与全链路验证。

4.1 创建部署目录

为 Chibisafe 建一个独立部署目录（本文以 /opt/chibisafe 为例，同机多实例时建议目录名带版本或用途后缀）：

mkdir -p /opt/chibisafe && cd /opt/chibisafe

完成后目录内应有 docker-compose.yml 与 Caddyfile 两个文件（与官方文档要求的目录结构一致，运行后自动生成 database/、uploads/、logs/ 三个数据子目录）。

4.2 编写 docker-compose.yml

创建 docker-compose.yml，内容如下（在官方范式基础上补了显式项目名、服务依赖与自定义网络；对外端口从官方示例的 24424 改为 8152）：

name: chibisafe-v6.7.0-stack

networks:
  chibisafe-net:
    name: chibisafe-v6.7.0-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24

services:
  chibisafe:
    image: chibisafe/chibisafe:latest
    container_name: chibisafe-v6.7.0-web
    environment:
      - BASE_API_URL=http://chibisafe_server:8000
    expose:
      - 8001
    depends_on:
      - chibisafe_server
    networks:
      - chibisafe-net
    restart: unless-stopped

  chibisafe_server:
    image: chibisafe/chibisafe-server:latest
    container_name: chibisafe-v6.7.0-server
    volumes:
      - ./database:/app/database:rw
      - ./uploads:/app/uploads:rw
      - ./logs:/app/logs:rw
    expose:
      - 8000
    networks:
      - chibisafe-net
    restart: unless-stopped

  caddy:
    image: caddy:2-alpine
    container_name: chibisafe-v6.7.0-caddy
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./uploads:/app/uploads:ro
    ports:
      - "8152:80"
    environment:
      - BASE_URL=":80"
    networks:
      - chibisafe-net
    restart: unless-stopped

逐项说明：

name: chibisafe-v6.7.0-stack：显式 Compose 项目名。同机跑多个组件的 Compose 栈时，显式项目名可避免目录同名导致 docker compose down 误删他人栈；
chibisafe（前端）：BASE_API_URL 告诉前端去哪调后端 API，值固定为栈内服务名 chibisafe_server:8000；只 expose 8001 不映射宿主端口，前端不直接对外；
chibisafe_server（后端）：挂载 database/（内嵌 SQLite 数据）、uploads/（上传文件本体）、logs/（运行日志）三个目录做持久化；同样只对栈内开放 8000；
caddy（入口）：唯一的对外服务，宿主 8152 → 栈内 80；挂载 Caddyfile（路由规则，只读）与 uploads/（只读，供 Caddy 直接吐文件）；BASE_URL=":80" 让 Caddy 按端口 80 匹配站点；
networks：显式指定 bridge 子网（本文用 10.89.56.0/24，取自服务器空闲网段；读者可按需修改，避免与既有网络冲突即可）；
restart: unless-stopped：服务异常退出或宿主机重启后自动拉起（手动 stop 的除外）。

4.3 编写 Caddyfile

在同目录创建 Caddyfile（完整照抄官方提供版本，不要自行改写路由）：

{
	servers {
		trusted_proxies static private_ranges
		client_ip_headers X-Forwarded-For X-Real-IP
	}
}

{$BASE_URL} {
	route {
		file_server * {
			root /app/uploads
			pass_thru
		}

		@api path /api/*
		reverse_proxy @api http://chibisafe_server:8000 {
			header_up Host {http.reverse_proxy.upstream.hostport}
			header_up X-Real-IP {http.request.header.X-Real-IP}
		}

		@docs path /docs*
		reverse_proxy @docs http://chibisafe_server:8000 {
			header_up Host {http.reverse_proxy.upstream.hostport}
			header_up X-Real-IP {http.request.header.X-Real-IP}
		}

		reverse_proxy http://chibisafe:8001 {
			header_up Host {http.reverse_proxy.upstream.hostport}
			header_up X-Real-IP {http.request.header.X-Real-IP}
		}
	}
}

路由逻辑解读（顺序敏感）：

file_server 把所有「未命中后续匹配」的 GET 请求直接导向 uploads/ 目录——上传文件的直链下载由 Caddy 静态吐出，不走应用进程；
@api 匹配 /api/*，转发后端 8000（header_up 透传真实客户端 IP）；
@docs 匹配 /docs*，转发后端 8000——这是后端自带的 API 文档页（Scalar 风格 OpenAPI 浏览界面）；
兜底 reverse_proxy 转发前端 8001（页面、静态资源）。

⚠️ 注意：官方文档特别强调该文件必须原样保留，特别是「文件直出 + 两条反代」的 route 结构；自行改写会导致直链 404 或前端 API 断裂。若把 Chibisafe 放到 Cloudflare 等代理之后，宿主机反代需按官方文档补 trusted_proxies 与 X-Forwarded-For 透传（见官方文档 Reverse proxy 一节）。

4.4 启动服务栈

cd /opt/chibisafe && docker compose up -d

实测回显（首次启动，镜像已拉取完毕）：

[+] Running 9/9
 ✔ Network chibisafe-v6.7.0-net             Created
 ✔ Container chibisafe-v6.7.0-web           Created
 ✔ Container chibisafe-v6.7.0-server        Created
 ✔ Container chibisafe-v6.7.0-caddy         Created
 ✔ Container chibisafe-v6.7.0-caddy         Started
 ✔ Container chibisafe-v6.7.0-server        Started
 ✔ Container chibisafe-v6.7.0-web           Started

三服务均为 Created → Started 即启动成功。首次启动时后端会在挂载的 database/ 目录里初始化内嵌数据库并执行迁移，uploads/ 下自动生成 tmp/、live/、zips/、thumbs/ 等工作子目录。

4.5 验证服务可用

先看栈内三服务状态：

docker compose ps

实测回显：

NAME                      IMAGE                               COMMAND                  SERVICE            CREATED          STATUS          PORTS
chibisafe-v6.7.0-caddy    caddy:2-alpine                      "caddy run --config …"   caddy              21 seconds ago   Up 20 seconds   443/tcp, 2019/tcp, 443/udp, 0.0.0.0:8152->80/tcp, [::]:8152->80/tcp
chibisafe-v6.7.0-server   chibisafe/chibisafe-server:latest   "docker-entrypoint.s…"   chibisafe_server   21 seconds ago   Up 19 seconds   8000/tcp
chibisafe-v6.7.0-web      chibisafe/chibisafe:latest          "docker-entrypoint.s…"   chibisafe          21 seconds ago   Up 19 seconds   8001/tcp

再用两个探活端点验证前后端均已就绪（/api/version 走 Caddy → 后端链路）：

curl -s http://127.0.0.1:8152/api/version

实测回显：

{"version":"6.7.0"}

curl -s http://127.0.0.1:8152/api/health

实测回显：

{"status":"yes"}

curl -sI http://127.0.0.1:8152/ | head -3

实测回显：

HTTP/1.1 200 OK
Cache-Control: private, no-cache, no-store, max-age=0, must-revalidate
Content-Type: text/html; charset=utf-8

三个回显分别确认：后端版本为 6.7.0、健康检查通过、前端首页 200。浏览器访问 http://<服务器IP>:8152 应能看到 Chibisafe 首页。

4.6 首次登录与修改默认密码

首次安装的默认账号与密码均为 admin（官方文档以 danger 级别提示必须立即修改）。浏览器打开 http://<服务器IP>:8152/login，用 admin / admin 登录。

登录后立即修改密码：进入右上角头像 → Account Settings（账户设置）→ 修改密码（本文演示统一改为 q1w2e3r4）。也可以用 REST API 完成同样动作（见 4.7 的登录取 token 方式）：

curl -s -X POST http://127.0.0.1:8152/api/auth/password/change \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"password":"admin","newPassword":"q1w2e3r4"}'

实测回显：

{"message":"The password was changed successfully"}

用新密码重新登录确认生效（回执中 passwordEditedAt 字段从 null 变为时间戳）：

curl -s -X POST http://127.0.0.1:8152/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测回显（JWT 节选）：

{"message":"Successfully logged in.","user":{"uuid":"6fd65081-c127-479d-8e21-f1d3c301f746","username":"admin","roles":[{"name":"owner"},{"name":"admin"}],"apiKey":null,"passwordEditedAt":"2026-10-30T05:22:24.018Z"},"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGliaXNhZmUiLCJzdWIiOjEs…（JWT 其余部分略）"}

💡 说明：token 字段即 JWT，有效期内可作为 Authorization: Bearer <JWT_TOKEN> 调用 REST API；后续命令中的 $JWT_TOKEN 均指从该回执 token 字段取到的值。API 的完整用法见本专栏《Chibisafe v6.7.0 API 使用详解》。

4.7 上传与分享全链路验证

本节用一条完整链路验证部署质量：单文件上传 → 直链下载 → 分块上传 → 短链分享。

第一步：单文件上传（REST API 形态）

先准备一个测试文件并登录拿 JWT（默认密码场景见上节；以下用改密后的 q1w2e3r4）：

echo "hello from chibisafe v6.7.0 test" > hello.txt
JWT_TOKEN=$(curl -s -X POST http://127.0.0.1:8152/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')

上传（/api/upload 接收 multipart 表单，字段名固定为 file）：

curl -s -X POST http://127.0.0.1:8152/api/upload \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -F "file=@hello.txt;type=text/plain"

实测回显：

{"name":"cX46Pk6hqQYr.txt","uuid":"5f0d7605-2a27-4e21-ba54-bd83efae151e","url":"http://chibisafe_server:8000/cX46Pk6hqQYr.txt"}

回执解读：服务端把文件重命名为 12 位随机标识 cX46Pk6hqQYr.txt（行为由设置项 generatedFilenameLength 控制），uuid 是文件的内部标识；url 显示的是后端内部地址，公网访问一律走 http://<服务器IP>:8152/<文件名>。

第二步：直链下载验证

curl -s http://127.0.0.1:8152/cX46Pk6hqQYr.txt

实测回显：

hello from chibisafe v6.7.0 test

带响应头看一次（确认下载由 Caddy 直出并带安全头）：

curl -sI http://127.0.0.1:8152/cX46Pk6hqQYr.txt

实测回显：

HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Length: 33
Content-Type: text/plain; charset=utf-8
Etag: "dmhx82ygl9yq-x"
Last-Modified: Fri, 30 Oct 2026 05:24:44 GMT
Server: Caddy
Vary: Accept-Encoding
Date: Fri, 30 Oct 2026 05:24:51 GMT

Server: Caddy 与 Accept-Ranges: bytes 印证了「Caddy 静态直出、支持断点续传」的架构设计；生产部署下官方 Caddyfile 还会附加 Content-Security-Policy: sandbox 等上传内容防护头。

第三步：分块上传验证（大文件路径）

大文件会被前端按 chunkSize（默认 81MB）分块上传。用 curl 模拟 3 块上传一个 3MB 文件（chibi-uuid、chibi-chunk-number、chibi-chunks-total 三个请求头声明分块坐标，表单字段 name/type/size 携带原始文件元数据）：

dd if=/dev/urandom of=big.bin bs=1M count=3
split -b 1m big.bin part_
UUID=$(uuidgen)
curl -s -o /dev/null -w 'chunk1 http=%{http_code}\n' -X POST http://127.0.0.1:8152/api/upload \
  -H "Authorization: Bearer $JWT_TOKEN" -H "chibi-uuid: $UUID" \
  -H "chibi-chunk-number: 1" -H "chibi-chunks-total: 3" \
  -F "name=big.bin" -F "type=application/octet-stream" -F "size=5242880" \
  -F "file=@part_aa"
curl -s -o /dev/null -w 'chunk2 http=%{http_code}\n' -X POST http://127.0.0.1:8152/api/upload \
  -H "Authorization: Bearer $JWT_TOKEN" -H "chibi-uuid: $UUID" \
  -H "chibi-chunk-number: 2" -H "chibi-chunks-total: 3" \
  -F "name=big.bin" -F "type=application/octet-stream" -F "size=5242880" \
  -F "file=@part_ab"
curl -s -X POST http://127.0.0.1:8152/api/upload \
  -H "Authorization: Bearer $JWT_TOKEN" -H "chibi-uuid: $UUID" \
  -H "chibi-chunk-number: 3" -H "chibi-chunks-total: 3" \
  -F "name=big.bin" -F "type=application/octet-stream" -F "size=5242880" \
  -F "file=@part_ac"

实测回显：

chunk1 http=204
chunk2 http=204
{"name":"GK9xP21EayQv.bin","uuid":"ba90bfa3-64d0-4dd4-ac6f-64efd3529e18","url":"http://chibisafe_server:8000/GK9xP21EayQv.bin"}

中间块返回 204 No Content（服务端确认收块、未完成合并），最后一块返回 200 并携带合并后的文件信息。下载合并结果并校验与原文件一致：

curl -s http://127.0.0.1:8152/GK9xP21EayQv.bin -o downloaded.bin
md5sum big.bin downloaded.bin

实测回显：

60c9386ab1e446458d9fce89d8bb9a97  big.bin
60c9386ab1e446458d9fce89d8bb9a97  downloaded.bin

md5 一致，分块合并无损。

第四步：短链分享验证

短链功能默认关闭（此时创建会得到 501），先在管理后台开启：DashBoard → Settings → URL Shortener 相关开关打开；等价的 REST 调用（settings 数组每项须带 key/value/type 三元组）：

curl -s -X POST http://127.0.0.1:8152/api/admin/service/settings \
  -H "Authorization: Bearer $JWT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"settings":[{"key":"useUrlShortener","value":true,"type":"boolean"}]}'

实测回显：

{"message":"Settings updated"}

关闭状态下的对照回执（改前实测）：

{"statusCode":501,"error":"Not Implemented","message":"URL shortener is disabled"}

创建一条短链（vanity 为自定义短链码，服务端会把连字符规范化为下划线）：

curl -s -X POST http://127.0.0.1:8152/api/link/create \
  -H "Authorization: Bearer $JWT_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://github.com/chibisafe/chibisafe","vanity":"chibisafe-repo"}'

实测回显：

{"message":"Successfully created link","link":{"uuid":"7801153a-f405-4be4-9529-daaa0243fcb5","identifier":"chibisafe_repo","link":"http://chibisafe_server:8000/l/chibisafe_repo"}}

访问短链（公网形态为 http://<服务器IP>:8152/l/chibisafe_repo）：

curl -sI http://127.0.0.1:8152/l/chibisafe_repo | grep -iE 'HTTP/|^location'

实测回显：

HTTP/1.1 307 Temporary Redirect
Location: /api/link/chibisafe_repo

307 跳转到后端解析端点并最终重定向到目标 URL，短链分享链路可用。至此「部署 → 登录改密 → 上传（单文件/分块）→ 直链下载 → 短链分享」全链路验证完成。

五、数据持久化说明

栈内只有后端与 Caddy 挂载了宿主目录，升级或重建栈时数据安全边界如下：

宿主目录（部署目录下）	栈内路径	内容	备份优先级
`./database/`	`/app/database`	内嵌 SQLite 数据库（用户、文件元数据、设置、短链、相册）	★★★ 必须
`./uploads/`	`/app/uploads`	上传文件本体 + 缩略图 + zip 打包缓存	★★★ 必须
`./logs/`	`/app/logs`	运行日志	★ 可选

备份与迁移的最小动作：停栈后把 database/ 与 uploads/ 两个目录整体拷走即可（官方对 v5→v6 迁移的口径也是复制这两个目录，来源：仓库 README，查询日期 2026-10-30）。SQLite 是单文件库，在线备份建议先 docker compose stop chibisafe_server 再拷，避免写一半的库文件。

⚠️ 注意：uploads/tmp/ 是分块上传的暂存区，uploads/thumbs/ 是缩略图缓存，二者可安全清理但会中断进行中的分块上传/触发缩略图重建。

六、环境变量表

三个服务的 Compose 环境变量全集（官方 compose 范式内出现的全部变量）：

服务	变量	实测值	作用
chibisafe（前端）	`BASE_API_URL`	`http://chibisafe_server:8000`	前端调用后端 API 的基地址，固定指向栈内后端服务名
caddy（入口）	`BASE_URL`	`":80"`	Caddyfile 站点匹配表达式，保持 `":80"` 即可

💡 说明：Chibisafe 的业务配置（站点名、上传限制、存储后端等 41 项）不在环境变量里，而是存于内嵌数据库、由管理后台读写——这是 v6 与许多「配置全靠 env」产品的一个显著区别，逐项含义见本专栏《Chibisafe v6.7.0 配置参数详解》。

七、配置参数说明

部署层面需要关注的参数与默认行为（均为 v6.7.0 实测值）：

对外端口：compose 中 8152:80 的左侧数字，改成任意空闲端口即可，宿主机反代统一指向它；
分块大小 chunkSize：默认 81000000 字节（约 81MB），前端按此切片上传，兼顾单请求失败重传成本与吞吐；
单文件上限 maxSize：默认 1000000000 字节（约 1GB），超过直接拒绝（File is too big）；
限流：默认每窗口 rateLimitWindow=1000（毫秒）内最多 rateLimitMax=100 个请求，实测响应头 X-Ratelimit-Limit: 100；
文件名策略：默认生成 12 位随机名（generatedFilenameLength=12），generateOriginalFileNameWithIdentifier=false（不保留原名），enableMixedCaseFilenames=true（允许大小写混合）；
扩展名黑名单：默认阻止 .jar,.exe,.msi,.com,.bat,.cmd,.scr,.ps1,.sh，且 blockNoExtension=true（无扩展名文件一并拒绝）；
访问模式：publicMode=false、userAccounts=false（默认仅注册用户可上传）。

以上设置全部可在管理后台 Dashboard → Settings 里修改并即时生效（无需重启栈），也可经 POST /api/admin/service/settings 修改。

八、配置文件挂载

本栈的配置与数据挂载关系汇总：

宿主路径	栈内路径	挂载模式	说明
`/opt/chibisafe/Caddyfile`	`/etc/caddy/Caddyfile`	只读	入口路由规则，官方要求原样保留
`/opt/chibisafe/database`	`/app/database`	读写	SQLite 数据库文件
`/opt/chibisafe/uploads`	`/app/uploads`（后端，读写）	读写	上传文件本体（后端写入）
`/opt/chibisafe/uploads`	`/app/uploads`（Caddy，只读）	只读	文件直出目录（Caddy 读取）
`/opt/chibisafe/logs`	`/app/logs`	读写	运行日志

要换宿主数据盘时，把三个数据目录整体迁移后修改 compose 中的左侧路径即可；Caddyfile 变更后执行 docker compose restart caddy 生效。

九、常用运维命令

均在部署目录 /opt/chibisafe 下执行：

# 查看三服务状态
docker compose ps

实测回显（正常运行态）：

NAME                      IMAGE                               STATUS          PORTS
chibisafe-v6.7.0-caddy    caddy:2-alpine                      Up 20 seconds   0.0.0.0:8152->80/tcp
chibisafe-v6.7.0-server   chibisafe/chibisafe-server:latest   Up 19 seconds   8000/tcp
chibisafe-v6.7.0-web      chibisafe/chibisafe:latest          Up 19 seconds   8001/tcp

# 跟踪后端日志（排障首选）
docker compose logs -f chibisafe_server

实测回显（节选）：

[05:26:08.614] INFO (38): GET /api/files 200 6ms 10.89.56.1

# 重启单个服务（改 Caddyfile 后）
docker compose restart caddy

# 停止与销毁栈（数据目录保留）
docker compose down

# 升级到新版本
docker compose pull && docker compose up -d

三服务资源占用实测（空闲态，供容量规划参考）：

docker stats --no-stream --format '{{.Name}}\t{{.MemUsage}}' | grep chibisafe

实测回显：

chibisafe-v6.7.0-web      59.42MiB / 15.57GiB
chibisafe-v6.7.0-server   154.3MiB / 15.57GiB
chibisafe-v6.7.0-caddy    62.9MiB / 15.57GiB

合计常驻内存约 280MB，1C2G 以上规格的虚机即可承载轻量使用。

十、常见问题

Q1：curl http://127.0.0.1:8152/ 一直 502/连接被拒？ 先 docker compose ps 看三服务是否全部 Up；再 docker compose logs caddy 看 Caddyfile 是否加载成功（常见错误：Caddyfile 拼写错误、uploads/ 目录未挂载导致 file_server 起不来）。Caddyfile 必须与 4.3 节逐字一致。

Q2：直链下载 404，但管理后台能看到文件？ uploads/ 在后端（读写）与 Caddy（只读）两处都要挂载。只挂了后端会导致 Caddy 找不到文件本体。核对 compose 第八节挂载表。

Q3：上传报 File type is not allowed？ 命中了扩展名黑名单（默认 .jar,.exe,.msi,.com,.bat,.cmd,.scr,.ps1,.sh）或 blockNoExtension（无扩展名拒绝）。在管理后台 Settings 里调整黑名单或开关。

Q4：上传报 You are over your storage quota？ 当前用户已用空间超过配额（usersStorageQuota，0 表示不限；管理员可为单个用户单独设额）。清理文件或在后台调额。

Q5：分块上传 curl 调用最后一块报错 The "path" argument must be of type string？ 分块上传的 multipart 里必须带 name（原始文件名）等表单字段——分块模式下服务端靠该字段推导合并后文件的扩展名，漏掉即触发该错误（v6.7.0 实测复现）。按 4.7 第三步的 -F "name=..." -F "type=..." -F "size=..." 补齐即可。

Q6：忘记 admin 密码？ 最简方式：停栈删库重建（会丢失全部数据，仅适合新实例）；或用另一个管理员账号在后台 User Management 里重置；没有备用管理员时，可用 SQLite 工具打开 database/ 下的库文件按官方社区方案重置密码哈希。

Q7：升级后直链全部异常？ 官方 README 明确：安全响应头策略随 Caddyfile 而非镜像下发，只升级镜像不会更新挂载的 Caddyfile。升级时同步用官方仓库最新 Caddyfile 覆盖本地文件并 docker compose restart caddy（来源：仓库 README「Uploaded file security」节，查询日期 2026-10-30）。

十一、参考链接

官方 Docker 部署文档：https://chibisafe.app/docs/installation/running-with-docker
官方仓库：https://github.com/chibisafe/chibisafe
官方 Caddyfile 范本（随版本更新）：https://github.com/chibisafe/chibisafe/blob/master/Caddyfile
本专栏配套篇目：《Chibisafe 介绍与选型指南》、《Chibisafe v6.7.0 配置参数详解》、《Chibisafe v6.7.0 API 使用详解》

（文中所有回显均为 2026-10-30 于 Ubuntu 22.04 实机部署 v6.7.0 的实测输出。）