Zipline 4.8.2 配置参数详解

目标：把 Zipline 4.8.2 的全部配置项讲透——配置分几层、从哪里看、从哪里改、每个参数管什么、默认值多少、改完怎么生效、改错了会怎样。本文所有默认值与合并结果均来自实机 ziplinectl read-config 输出，所有行为类结论（大小限制、限流、命名格式、环境变量覆盖）均有实测回显支撑。

一、环境信息

• 被测版本：Zipline 4.8.2（/api/version 实测返回 "details":{"version":"4.8.2","sha":"5fe2792"}）
• 实机环境：Ubuntu 24.04.5 LTS（x86_64），Docker 29.9.2 + Docker Compose v5.6.1，PostgreSQL 16
• 实例地址：http://192.168.1.172:8142（直连）/ http://192.168.1.172:8143（nginx 反代）
• 部署方式：Docker Compose，完整过程见 《Zipline 4.8.2 Docker Compose 部署指南》
• 配置查阅命令均在部署目录 /opt/zipline 下执行；示例账号 root / q1w2e3r4

二、前置条件

1. 已按部署指南完成实例搭建并通过健康检查（curl -s http://127.0.0.1:8142/api/healthcheck 返回 {"pass":true}）；
2. 具备服务器上的部署目录读写权限（.env、docker-compose.yml 所在目录）；
3. 想改「仅环境可配」的 core/datasource 类参数，需要能重启服务；想改 dashboard 类参数，需要 SUPERADMIN 账号登录后台。

三、配置的分层模型与查看/修改方式

3.1 两层配置：环境变量覆盖 dashboard

Zipline 的配置分两层，优先级为 环境变量 > Server Settings 后台（存数据库）> 内置默认值：

• 绝大多数设置可以在后台 Server Settings（路径 /dashboard/admin/settings，仅超级管理员可见）里改，值存进数据库；
• 同名设置一旦用环境变量提供，环境变量覆盖数据库值，且后台里该字段变成只读；
• core 与 datasource 两类的全部选项只能通过环境变量配置，后台没有对应入口。

这个「覆盖」行为不是靠文档口头保证的，ziplinectl read-config 的 DEBUG 日志直接列出了被环境变量覆盖的键（实测回显）：

[2026-11-01T08:48:07 DEBUG  config.read] overridden db settings from env vars overridden=["coreTrustProxy","coreTrustedProxies","coreReturnHttpsUrls","filesRoute","filesLength","filesDefaultFormat","filesMaxFileSize","urlsRoute","urlsLength","featuresThumbnailsEnabled","featuresThumbnailsInstantaneous"]

本次实例的 .env 恰好写了这 11 个变量，日志逐一对应，无一遗漏。

3.2 查看当前生效配置：read-config

read-config 输出「Zipline 实际看到的配置」JSON（环境变量与数据库值合并后的最终态），是排「改了没生效」问题的第一工具：

docker compose exec zipline ziplinectl read-config

实测回显（节选，敏感值已打码）：

{"core":{"port":3000,"hostname":"0.0.0.0","secret":"bNI6****","returnHttpsUrls":false,"defaultDomain":null,"tempDirectory":"/zipline/uploads/.tmp","trustProxy":true,"trustedProxies":["10.89.62.0/24"],"databaseUrl":"postgres://zipline:PlG0****@postgresql:5432/zipline","database":{"username":null,"password":null,"host":null,"port":null,"name":null}},
 "chunks":{"max":"95mb","size":"25mb","enabled":true},
 "tasks":{"deleteInterval":"30m","clearInvitesInterval":"30m","maxViewsInterval":"30m","thumbnailsInterval":"30m","metricsInterval":"30m","cleanThumbnailsInterval":"1d"},
 "files":{"route":"/f","length":12,"defaultFormat":"date","disabledTypes":[],"disabledTypesDefault":null,"disabledExtensions":[],"maxFileSize":"5mb","defaultExpiration":null,"maxExpiration":null,"assumeMimetypes":false,"defaultDateFormat":"YYYY-MM-DD_HH:mm:ss","removeGpsMetadata":false,"randomWordsNumAdjectives":2,"randomWordsSeparator":"-","defaultCompressionFormat":"jpg","maxFilesPerUpload":1000,"extensionlessUrls":false},
 "urls":{"route":"/s","length":8},
 "datasource":{"type":"local","local":{"directory":"./uploads"}},
 "ratelimit":{"enabled":true,"max":10,"window":null,"adminBypass":true,"allowList":[]}}

💡 技术拓展：read-config 里的 features.userRegistration:false 是个好例子——.env 里并没有写 FEATURES_USER_REGISTRATION，这个 false 是此前在后台「Features」页关掉注册后存进数据库的值。它说明 read-config 展示的是合并后的最终生效值，而非单一来源。

3.3 导出可复用配置：export-config

export-config 把当前生效配置导出成环境变量格式（默认只导出与内置默认值不同的键，适合精简 .env）：

docker compose exec zipline ziplinectl export-config

实测回显（节选）：

TASKS_DELETE_INTERVAL="30m"
TASKS_CLEAR_INVITES_INTERVAL="30m"
TASKS_MAX_VIEWS_INTERVAL="30m"
FILES_RANDOM_WORDS_NUM_ADJECTIVES=2
FEATURES_ROBOTS_TXT=true
INVITES_LENGTH=6
WEBSITE_THEME_DARK="builtin:dark_gray"
WEBSITE_THEME_LIGHT="builtin:light_gray"
PWA_ENABLED=false

加 -y 导出成可直接嵌进 Compose 文件的 YAML 格式，加 -d 连默认值一起导出全量清单。两个开关可组合（export-config -y -d）。

3.4 修改与生效方式

⚠️ 注意一个容易踩的坑：docker compose restart 只重启进程、不会重新读取 .env——环境变量是容器创建时注入的。改了 .env 必须 up -d（触发重建）才生效，只 restart 的话 read-config 里看到的还是旧值。

四、参数总览

按 read-config 的 JSON 结构，全部配置分 15 类。类别、环境变量前缀与配置渠道对照如下：

必填项只有两个：CORE_SECRET 与数据库连接（DATABASE_URL，或 DATABASE_NAME/USERNAME/PASSWORD/HOST/PORT 五件套全给）。其余全部有默认值。

五、核心参数分类详解

5.1 core：连接、密钥与反代信任

要点与实测：

• 数据库连接二选一：DATABASE_URL 与五件套同时给时 DATABASE_URL 优先；五件套缺任何一个，服务直接拒绝启动。
• PGlite 模式：DATABASE_URL=pglite:///zipline/data/database 可去掉 PostgreSQL 依赖，数据库落在本地目录（注意存的是元数据，不是上传文件本体；目录必须持久化挂载，且要用绝对路径）。已有 PostgreSQL 数据时改 URL 不会搬数据，要先用 ziplinectl migrate-pglite 迁移（见部署指南）。
• 反代信任必须配对开启：本实例经 nginx 反代访问，.env 写了 CORE_TRUST_PROXY=true 与 CORE_TRUSTED_PROXIES=10.89.62.0/24（反代所在网段）。不配的话所有访客在限流与日志里都会被算成反代那一个 IP。read-config 实测回显 "trustProxy":true,"trustedProxies":["10.89.62.0/24"] 确认生效。
• _FILE 后缀：任何这类变量都可以写成 CORE_SECRET_FILE=/run/secrets/core_secret，值从文件读取，适合把密钥挪出 .env。

5.2 datasource：文件本体存哪

本实例实测为 local 模式，read-config 回显 "datasource":{"type":"local","local":{"directory":"./uploads"}}，上传的文件落在部署目录的 uploads/ 下（Compose 已把它 bind mount 出来，备份时与数据库一起备）。

💡 技术拓展：S3 兼容对象存储是文件分享服务的主流第二存储后端，常见选项与 Zipline 适配要点：

服务商	REGION	ENDPOINT	备注
AWS S3	真实区域（必填）	可不设	官方主路径
Cloudflare R2	auto/us-east-1	https://<account>.r2.cloudflarestorage.com	无真实区域概念
Backblaze B2	开户时给定（如 us-west-004）	https://s3.<region>.backblazeb2.com	—
自建 MinIO	任意	http://<host>:9000	通常需 FORCE_PATH_STYLE=true

Zipline 用通用 AWS SDK 对接，切换后端只动 DATASOURCE_ 变量；存量文件不会自动搬迁，跨后端迁移要用 ziplinectl import-dir（见 §5.9）。

5.3 files：上传路由、命名与大小

实测行为三连（本实例 FILES_DEFAULT_FORMAT=date、FILES_MAX_FILE_SIZE=5mb）：

1. date 命名生效：上传 big2m.bin 返回 "name":"2026-11-01_08:48:16.bin"——按 YYYY-MM-DD_HH:mm:ss 生成；
2. 重名自动加后缀：同一秒内连续上传同名结果，服务端依次命名 2026-11-01_08:48:52.txt、...-1.txt、...-2.txt，不会互相覆盖；
3. 超限拒绝且报错有误导性：上传 6MB 文件（超 5mb 上限）返回的不是「文件太大」，而是：

{"error":"E1062: No files in multipart/form-data request","code":1062,"statusCode":400}

multipart 解析器把超限文件静默丢弃后才报「请求里没有文件」，排障时务必用 read-config 核对 filesMaxFileSize（详见 §八 FAQ）。

5.4 urls：短链

实测：URLS_LENGTH=8 下创建短链返回 "code":"uNMfdrDa"（8 位）；带 vanity 自定义短码时返回 "vanity":"zipline-doc"、直链 http://127.0.0.1:8142/s/zipline-doc，访问返回 302 跳转到目标地址。接口细节见 《Zipline 4.8.2 常用操作与 API 详解》。

5.5 chunks：分块上传

read-config 实测回显 "chunks":{"max":"95mb","size":"25mb","enabled":true}。用途是让大文件绕过反代的单请求体限制（反代 client_max_body_size 只需容得下一片）。CHUNKS_MAX 与 FILES_MAX_FILE_SIZE 是两道独立的闸：前者管分块通道，后者管所有上传的文件大小上限。

5.6 tasks：后台任务周期

取值用相对时长写法（30m、1d、2h 这类 ms 格式）。改动需重启生效。依赖「定时过期删除」功能时注意：deletesAt 到期不是即时删除，最坏要等一个 TASKS_DELETE_INTERVAL 周期。

5.7 features：功能开关

⚠️ 事实纠偏：v4.8.2 源码中没有 Prometheus /metrics 端点（实测 curl http://127.0.0.1:8142/metrics 返回的是 Next.js 页面 HTML，不是指标文本）。FEATURES_METRICS_* 控制的是内置统计（/api/stats 接口与后台图表页），不要按 Prometheus 方案去接抓取器。

5.8 ratelimit：限流

两组对照实测（默认 max=10、窗口 1 分钟）：

• SUPERADMIN Token 一分钟内连续 12 次上传：全部 200——adminBypass 生效；
• 普通用户（demo，USER 角色）会话连续 12 次上传：前 10 次 200，第 11、12 次：

{"error":"Rate limit exceeded, retry in 1 minute","statusCode":429}

分块上传只有第一片计入限流；续传片带有效 token 不消耗额度。

5.9 其余类别（invites/mfa/oauth/domains/website/webhook/pwa）

这些类别参数较多但都是「开关 + 字符串」型，列关键项（默认值均出自 read-config 实测）：

• invites：INVITES_ENABLED=true、INVITES_LENGTH=6。邀请制实例的配方：关掉 FEATURES_USER_REGISTRATION、保持 invites 开启，后台生成邀请码发人。
• mfa：MFA_TOTP_ENABLED=false（默认关）、MFA_TOTP_ISSUER=Zipline；Passkey 三件套 MFA_PASSKEYS_ENABLED/RP_ID/ORIGIN 必须与实例域名匹配才能注册成功。
• oauth：每家四件套 OAUTH_<PROVIDER>_CLIENT_ID/CLIENT_SECRET/REDIRECT_URI，回调 URI 约定为 https://<实例>/api/auth/oauth/<provider>；通用 OIDC 另需 AUTHORIZE_URL/USERINFO_URL/TOKEN_URL，可选 END_SESSION_URL 做单点登出。OAUTH_LOGIN_ONLY=true 可禁掉本地密码登录。
• domains：DOMAINS=zip.example.com,zip2.example.com，用户在上传时可下拉选域名（每个域名都必须在 DNS 上指向本实例）。
• website：WEBSITE_TITLE=Zipline、WEBSITE_TITLE_LOGO、WEBSITE_LOGIN_BACKGROUND(_BLUR)、WEBSITE_THEME_DEFAULT=system、WEBSITE_THEME_DARK=builtin:dark_gray、WEBSITE_THEME_LIGHT=builtin:light_gray（后两值即本实例实测值）、WEBSITE_EXTERNAL_LINKS（JSON 数组）、WEBSITE_DEFAULT_AVATAR/WEBSITE_TOS（服务器本地路径）。
• discord / httpWebhook：DISCORD_WEBHOOK_URL 等通知类变量与 HTTP_WEBHOOK_ON_UPLOAD/ON_SHORTEN，消息模板支持 {file.name}{:zipline} 形式的变量与修饰符（::upper、::bytes、::utc 等）。
• pwa：PWA_ENABLED=false（默认关，read-config 实测一致）；开启需把 favicon 文件放进 public/ 目录。

ziplinectl import-dir <目录> 配合 datasource 变量还能把一批存量本地文件导入（或换后端时拷进 S3），详见 §5.10。

5.10 ziplinectl：配置相关的命令行工具

镜像内置 ziplinectl 管理命令（在 Compose 服务里执行：docker compose exec zipline ziplinectl <子命令>），与配置相关的实测输出：

list-users 实测回显（节选）：

[{"id":"x48cfnti1ir8atu0qbnha9oa","username":"root","role":"SUPERADMIN"},{"id":"nqcbgnte8j43i2a92nuzosu1","username":"demo","role":"USER"}]

六、生产配置模板

以下为公网单实例 + nginx 反代 + PostgreSQL 的推荐 .env（示例值可直接替换；密码类请用 openssl rand -base64 32 现生成）：

# ---- 必填 ----
POSTGRESQL_PASSWORD=<数据库密码>
CORE_SECRET=<openssl rand -base64 32 生成>

# ---- 对外形态 ----
CORE_RETURN_HTTPS_URLS=true
CORE_TRUST_PROXY=true
CORE_TRUSTED_PROXIES=<反代IP或CIDR>
CORE_DEFAULT_DOMAIN=zip.example.com

# ---- 文件策略（按容量与风险偏好）----
FILES_MAX_FILE_SIZE=100mb
FILES_MAX_FILES_PER_UPLOAD=10
FILES_ROUTE=/u
FILES_DEFAULT_FORMAT=random
FILES_LENGTH=6
FILES_ASSUME_MIMETYPES=true
FILES_DISABLED_TYPES=text/html,application/javascript
FILES_DISABLED_EXTENSIONS=exe,bat,dmg
FILES_REMOVE_GPS_METADATA=true

# ---- 短链 ----
URLS_ROUTE=/go
URLS_LENGTH=4

# ---- 注册策略：邀请制 ----
FEATURES_USER_REGISTRATION=false
INVITES_ENABLED=true

# ---- 缩略图（视频）----
FEATURES_THUMBNAILS_ENABLED=true
FEATURES_THUMBNAILS_NUM_THREADS=2

# ---- 限流 ----
RATELIMIT_ENABLED=true
RATELIMIT_MAX=10
RATELIMIT_WINDOW=60000
RATELIMIT_ADMIN_BYPASS=true

DEBUG=zipline

配套要点：DATABASE_URL 由 Compose 用 POSTGRESQL_PASSWORD 拼装（见部署指南），不要在 .env 里重复写死；反代上 client_max_body_size 至少等于 FILES_MAX_FILE_SIZE，走分块上传则只需容下 CHUNKS_SIZE。

七、常见问题

1. 改了 .env 没生效——restart 不重读 .env，必须 docker compose up -d 触发重建；用 read-config 核对最终值，并看 DEBUG 行里 overridden=[...] 是否包含你改的键。
2. 后台某个设置框是灰的——该键已被同名环境变量覆盖（§3.1 机制），想回后台管理就删掉 .env 里那行再重建。
3. 上传大文件报 E1062: No files in multipart/form-data request——大概率是超 FILES_MAX_FILE_SIZE，multipart 解析器静默丢件后报「没有文件」；核对 read-config 的 filesMaxFileSize，或改走分块上传接口。
4. 所有访客共享同一份限流额度 / 日志里 IP 全是反代地址——CORE_TRUST_PROXY 没开或 CORE_TRUSTED_PROXIES 没包含反代网段，改完 up -d 重建。
5. 换 CORE_SECRET 后全员掉线、Token 全失效——设计如此：Cookie 签名与 Token 加密都派生自它。先公告再换，换后各自重新登录、重新生成 Token。
6. 限流白名单加了 IP 没用——官方明确 RATELIMIT_ALLOW_LIST 在当前版本不生效（read-config 里能看到键，行为未实装）。
7. 按 Prometheus 抓 /metrics 拿到一堆 HTML——v4 没有 Prometheus 端点，统计走 /api/stats 接口或后台 metrics 页。

八、参考链接

• 官方配置总览：https://zipline.diced.sh/docs/config
• 官方 Core 配置：https://zipline.diced.sh/docs/config/core
• 官方 Datasource 配置：https://zipline.diced.sh/docs/config/datasource
• 官方 Settings 配置：https://zipline.diced.sh/docs/config/settings
• 官方 ziplinectl 文档：https://zipline.diced.sh/docs/guides/ctl
• 同系列：《Zipline 介绍与选型指南》、《Zipline 4.8.2 Docker Compose 部署指南》、《Zipline 4.8.2 常用操作与 API 详解》