Chibisafe v6.7.0 配置参数详解

目标：逐域讲清 Chibisafe v6.7.0 的全部 41 个运行参数（站点身份、上传与文件名、访问模式、限流、短链、S3 存储、页面内容等）的默认值、作用与修改方式，并给出可直接套用的生产配置模板。全部默认值与管理 API 修改行为均在 2026-10-30 于 Ubuntu 22.04 实机（v6.7.0）实测取得。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• Chibisafe 版本：v6.7.0（GET /api/version 实测返回 {"version":"6.7.0"}）
• 部署形态：官方三服务 Compose（前端 + 后端 + Caddy 入口，Web 端口 8152），部署步骤见 《Chibisafe v6.7.0 Docker Compose 部署指南》
• 参数载体：内嵌 SQLite 数据库（database/ 目录），非配置文件；管理后台（Dashboard → Settings）与 REST API 均可读写
• 实测取值方式：GET /api/admin/service/settings 一次性返回全部 41 项（实测 41 项与本文逐一对应）

二、前置条件

1. 已按部署指南完成 v6.7.0 部署并可登录管理后台（默认 admin，本文演示密码 q1w2e3r4）；
2. 拥有管理员（admin/owner 角色）账号——全部 41 项参数仅管理员可见可改；
3. 理解参数的两条修改通道（下节详述）：管理后台 UI 与 POST /api/admin/service/settings。

三、参数查看与修改方式

3.1 通道一：管理后台（推荐）

登录后进入右上角头像 → DashBoard → Settings，参数按 Tabs 分组展示（Server、URLs、Files、Users 等页签），所有修改即时保存、即时生效，无需重启任何服务（配置存于数据库，应用侧每次请求读取当前值）。

3.2 通道二：REST API（适合自动化）

先登录拿 JWT，再读全量参数：

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')
curl -s http://127.0.0.1:8152/api/admin/service/settings -H "Authorization: Bearer $JWT_TOKEN"

实测回显（节选，首尾）：

{"settings":[{"key":"serviceName","value":"change-me","type":"string"},{"key":"serveUploadsFrom","value":"","type":"string"},…（中间 37 项略）…{"key":"defaultSortOrder","value":"createdAt:desc","type":"select"}]}

修改参数的请求体格式有讲究：settings 是数组，每项必须同时携带 key、value、type 三个字段（缺 type 会被 zod 校验拒绝，实测报错如下）：

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}]}'

实测回显（错误示范）：

{"statusCode":400,"error":"Bad Request","message":"[\n  {\n    \"code\": \"invalid_type\",\n    \"expected\": \"string\",\n    \"received\": \"undefined\",\n    \"path\": [\n      \"settings\",\n      0,\n      \"type\"\n    ],\n    \"message\": \"Required\"\n  }\n]"}

补上 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"}

type 取值与参数表中的类型一致（string/number/boolean/select/text）。单次请求可同时提交多项。

⚠️ 注意：部分参数（如 secret）修改后会使既有登录会话与 API Key 失效，详见下文对应条目。

四、参数总览

以下 41 项为 GET /api/admin/service/settings 于 2026-10-30 实测返回的完整清单（按功能域分组，默认值为实测原值）：

💡 技术拓展：自托管文件服务的「配置存放位置」常见三种流派——

流派	代表	特点
配置文件（YAML/TOML/env）	大多数 Go/Java 服务	版本化友好，改配置需重启
数据库 + Web 后台	Chibisafe、Zipline	即改即生效，双通道（UI/API）读写
混合（env 引导 + 后台细化）	Mastodon 等	引导层在 env，业务层在库

Chibisafe 属第二种：本文 41 项全部存在 SQLite 里，compose 环境变量只有 BASE_API_URL/BASE_URL 两个「路由引导」变量。

五、核心参数分类详解

5.1 站点身份与展示（8 项）

这组参数决定站点「叫什么、长什么样、SEO 元信息是什么」：

• serviceName（string，默认 change-me）：站点名称，显示在浏览器标题、首页与邮件文案中。实测修改后首页标题立即变化。部署后第一件事就是改它；
• serveUploadsFrom（string，默认空）：文件直链的服务来源地址覆盖。留空时直链用请求本身的 Host 头生成（本文实测上传回执 url 字段显示为后端内部地址，公网访问走入口地址即可）；若站点在反代/CDN 之后且希望直链强制走特定域名，填入该域名；
• backgroundImageURL（string，默认空）：首页背景图 URL；
• logoURL（string，默认空）：站点 Logo 图 URL，留空用内置 Logo；
• metaDescription / metaKeywords / metaTwitterHandle / metaDomain（string）：HTML <meta> 标签内容，供搜索引擎与社交卡片抓取。默认值是占位文案（description for please-change-me.com 🚀 等），公网站点应替换为真实描述、关键词、Twitter 账号与域名；
• useMinimalHomepage（boolean，默认 false）：是否启用极简首页（隐藏介绍性文案，只保留上传区）。对外做纯工具站时建议开启。

5.2 上传与文件名（10 项）

这组决定「能传多大、怎么切片、叫什么名、允许什么类型」：

• chunkSize（number，默认 81000000 ≈ 81MB）：分块上传的单块大小。前端按此切片；单块失败只需重传该块。内网万兆环境可调大，公网移动网络用户多时保持默认；
• maxSize（number，默认 1000000000 ≈ 1GB）：单文件总大小上限，超过即拒绝。实测超限返回 File is too big；设 0 表示不限制（同时依赖磁盘容量）；
• generateZips（boolean，默认 true）：允许把相册/多文件打包成 zip 下载（服务端在 uploads/zips/ 生成打包缓存）。磁盘紧张可关闭；
• generatedFilenameLength（number，默认 12）：随机文件名长度。实测上传 hello.txt 后落盘为 12 位标识名 cX46Pk6hqQYr.txt；
• generateOriginalFileNameWithIdentifier（boolean，默认 false）：开启后文件名变为「slug 化原名-标识.扩展名」（如 hello-cX46Pk6hqQYr.txt），URL 可读性更好但暴露原名；
• enableMixedCaseFilenames（boolean，默认 true）：允许生成的文件名含大写字母（实测默认生成的 cX46Pk6hqQYr 即大小写混合）；关闭则全小写（Linux 大小写敏感，混合可轻微降低枚举碰撞）；
• blockedExtensions（string，默认 .jar,.exe,.msi,.com,.bat,.cmd,.scr,.ps1,.sh）：扩展名黑名单，命中即拒绝（实测报错 File type is not allowed）。逗号分隔，可按需增删；
• blockNoExtension（boolean，默认 true）：无扩展名文件一并拒绝。公网实例建议保持 true；
• generateThumbnails（boolean，默认 true）：为图片/视频生成缩略图（存 uploads/thumbs/）。纯文件床可关闭省 CPU；
• saveDuplicatesToAlbum（boolean，默认 false）：向相册上传重复文件时是否仍保存副本。

5.3 访问模式与用户配额（3 项）

• publicMode（boolean，默认 false）：公开模式。开启后未登录访客也能上传（首页即传），关闭后仅注册用户可传（后端源码口径：!SETTINGS.publicMode && !req.user 时返回 Only registered users are allowed to upload files.）。公网实例慎开——即便开启也建议配合限流与黑名单；
• userAccounts（boolean，默认 false）：开启注册通道（配合 Invites 邀请码体系，管理员可在后台生成邀请码控制注册）。典型组合：publicMode=false + userAccounts=true = 邀请制社区；
• usersStorageQuota（number，默认 0）：新用户的默认存储配额（字节），0 不限。管理员还可在后台 User Management 里为单个用户单独设额（对应 POST /api/admin/user/{uuid}/quota）。

5.4 限流与安全（3 项）

• rateLimitWindow（number，默认 1000，单位毫秒）+ rateLimitMax（number，默认 100）：滑动窗口限流，即默认每秒每 IP 最多 100 个请求。实测响应头印证：X-Ratelimit-Limit: 100、X-Ratelimit-Remaining: 99、X-Ratelimit-Reset: 1。公开模式下建议收紧（如 500ms/50 次）；
• secret（string，默认为安装时生成的 48 位随机串）：JWT 签名密钥。修改后所有已签发的登录态与依赖签名的令牌立即失效（所有用户需重新登录）。此值等同系统主密钥，严禁泄露——管理 API 返回该值仅管理员可见，截图/分享日志时注意遮挡。

5.5 短链与相册（3 项）

• useUrlShortener（boolean，默认 false）：内置短链服务开关。实测默认关闭时 POST /api/link/create 返回 {"statusCode":501,"error":"Not Implemented","message":"URL shortener is disabled"}；开启后同一请求成功返回短链对象。短链访问路径为 /l/<标识>（实测 307 跳转）；
• generatedLinksLength（number，默认 8）：短链随机标识长度（不指定 vanity 时生成 8 位标识）；
• generatedAlbumLength（number，默认 6）：相册分享标识长度。

⚠️ 注意：自定义短链码（vanity）会被服务端规范化——实测传 chibisafe-repo，落库标识为 chibisafe_repo（连字符转下划线），写文档或二维码时以返回的 identifier 为准。

5.6 存储后端：本地盘与 S3（9 项）

默认存储为本地目录（uploads/），下列 9 项用于切换 S3 兼容对象存储（AWS S3、MinIO、Wasabi、Cloudflare R2 等，来源：仓库 README「🗄️ S3 Storage Support」与官方文档 Storage 分区，查询日期 2026-10-30）：

• useNetworkStorage（boolean，默认 false）：总开关。开启后上传流程变为「后端签发预签名 PUT URL → 客户端直传对象存储」（后端源码实测：返回体为 {url, identifier, publicUrl} 三元组），本地 uploads/ 不再存放新文件；
• S3Region / S3Bucket / S3AccessKey / S3SecretKey / S3Endpoint（string，默认空）：对象存储五要素——区域、桶名、访问密钥对、端点。MinIO/R2 等自建 S3 填 S3Endpoint（如 http://minio:9000）；
• S3PathStyle（boolean，默认 false）：是否使用 path-style 寻址（endpoint/bucket/key）。MinIO 本地部署必须开 true（虚拟主机样式对自建域名不友好）；AWS 主流区域用默认 false；
• S3PublicUrl（string，默认空）：对象存储的公开访问基址，生成直链时用。留空时回退 S3Endpoint；
• serveUploadsFrom（见 5.1）在 S3 模式下也影响直链拼接。

切换动作全部在管理后台完成，无需重启；已存在的本地文件不会被迁移，官方建议新实例在首次启用前决定存储形态。

💡 技术拓展：S3 兼容存储的两种寻址风格对比——

风格	URL 形态	适用
virtual-hosted style	bucket.endpoint/key	AWS S3 + 泛域名证书
path style	endpoint/bucket/key	MinIO/自建 S3、内网部署

Chibisafe 以 S3PathStyle 开关适配两种；本文实测环境未启用 S3，上述行为以官方文档与设置项描述为准。

5.7 页面内容与系统杂项（5 项）

• privacyPolicyPageContent / termsOfServicePageContent / rulesPageContent（text，默认空）：隐私政策、服务条款、社区规则三个静态页的正文（Markdown）。公网开放注册/公开上传的实例建议至少填写规则页；
• disableUpdateCheck（boolean，默认 false）：关闭版本更新检查（后台会对比 GitHub 最新 Release 提示升级）。内网隔离环境可开启消除告警；
• defaultSortOrder（select，默认 createdAt:desc）：文件列表默认排序，可选时间/名称等维度升降序。

5.8 部署层变量（compose 环境变量）

业务参数之外，Compose 栈里还有 2 个「路由引导」级环境变量（改动需重启对应服务）：

后端自身的运行形态（监听端口 8000、数据库路径 /app/database 等）由官方镜像内建，无需也不建议覆盖。

六、生产配置模板

以下为「公网、邀请制、大文件友好」场景的推荐参数集（适用 2C4G 以上、NVMe SSD、月上传量 100GB 以内的实例；全部可用 3.2 节的 API 批量下发）：

{
  "settings": [
    { "key": "serviceName", "value": "MyFileHub", "type": "string" },
    { "key": "useUrlShortener", "value": true, "type": "boolean" },
    { "key": "publicMode", "value": false, "type": "boolean" },
    { "key": "userAccounts", "value": true, "type": "boolean" },
    { "key": "usersStorageQuota", "value": 10737418240, "type": "number" },
    { "key": "rateLimitWindow", "value": 1000, "type": "number" },
    { "key": "rateLimitMax", "value": 50, "type": "number" },
    { "key": "chunkSize", "value": 52428800, "type": "number" },
    { "key": "maxSize", "value": 5368709120, "type": "number" },
    { "key": "blockNoExtension", "value": true, "type": "boolean" },
    { "key": "generateThumbnails", "value": true, "type": "boolean" },
    { "key": "metaDescription", "value": "自托管文件上传与分享服务", "type": "string" },
    { "key": "metaDomain", "value": "https://files.example.com", "type": "string" }
  ]
}

逐项解读：站点名替换默认 change-me；短链开启（若需要）；关闭公开上传、开启账号注册（邀请制）；用户默认配额 10GB；限流收紧到每秒 50 次；分块降到 50MB（公网上传更抗抖动）；单文件上限放宽到 5GB；保留无扩展名拦截与缩略图；SEO 元信息替换为真实域名与描述。

内网工具化场景（可信团队、追求省事）则反向：publicMode=true、userAccounts=false、maxSize 保持 1GB、限流放宽，其余默认即可。

七、常见问题

Q1：改了设置为什么没生效？ 确认改对通道：管理后台/POST /api/admin/service/settings 都是即改即生效的；若用 docker compose restart 反而会中断进行中的上传。若确实「改了没反应」，先 GET /api/admin/service/settings 回读确认 value 已变。

Q2：POST settings 报 Required 校验错误？ settings 数组每项必须带 key+value+type 三元组（见 3.2 实测报错回显）。漏 type 是最常见的翻车点。

Q3：短链接口返回 501？ useUrlShortener 默认关闭，这是产品语义而非故障（实测回执 URL shortener is disabled）。后台开启后重试。

Q4：换了 secret 后全体掉线？ 预期行为：secret 是 JWT 签名密钥，更换即全量会话失效。换密后重新登录即可，API Key 是否失效以实测为准（重新生成即可兜底）。

Q5：S3 切换后老文件还能访问吗？ 能。切换只影响新上传的落点，本地 uploads/ 既有文件仍在原直链可访问；但官方未提供自动迁移工具，存量迁移需自行搬对象（来源：官方文档 Storage 分区，查询日期 2026-10-30）。

Q6：blockedExtensions 改了还是能传被禁类型？ 黑名单按扩展名字符串匹配（.exe 形态，逗号分隔无空格），并受 blockNoExtension 联动；注意大小写（服务端按小写比较，实测逻辑对 .EXE 亦拦截）。改完用一个测试文件实测一次为准。

八、参考链接

• 官方文档（含 Storage/S3 说明）：https://chibisafe.app/docs/category/storage
• 官方仓库：https://github.com/chibisafe/chibisafe
• 官方 Docker 部署文档：https://chibisafe.app/docs/installation/running-with-docker
• 本专栏配套篇目：《Chibisafe 介绍与选型指南》、《Chibisafe v6.7.0 Docker Compose 部署指南》、《Chibisafe v6.7.0 API 使用详解》

（文中全部默认值、回执与报错均为 2026-10-30 于 Ubuntu 22.04 实机 v6.7.0 实测取得；官方文档类信息标注了查询日期。）