Gokapi 2.2.4 配置参数详解

目标：读懂 Gokapi 2.2.4 的全部配置项，并通过"修改 → 重启 → 验证"的闭环实测，掌握端口、认证、加密等级、S3 兼容存储与元数据库的切换方法。本文操作承接安装篇部署好的实例（服务器 10.89.62.2，管理员 admin/q1w2e3r4）。

一、配置体系概览

1.1 文件位置

Gokapi 的配置按目录约定存放，WorkingDirectory（或 --config-dir 指定的目录）下：

路径	内容
config/config.json	主配置文件
data/gokapi.sqlite	元数据库（默认 SQLite）
data/	文件本体存储（本地存储模式）

主配置文件权限为 600（仅属主可读），实测：

ls -la /opt/gokapi/config/

-rw------- 1 root root 1438 Oct 26 08:41 config.json

1.2 配置的生效方式

config.json 由安装向导生成，也可手工编辑。修改后需重启服务进程生效。涉及认证凭据（如管理员密码）的字段为哈希存储，手工改写会破坏校验，这类字段应通过 --reconfigure 向导或管理后台修改，详见 CLI 命令篇。

二、全参数拆解

以下为实测抓取的 v2.2.4 config.json 完整结构（部分安全字段值已随环境生成）：

{
  "Authentication": {
    "Method": "internal",
    "SaltAdmin": "H3Y1ZfI5vISnV8a6ifVmLoKgBYn5WS",
    "SaltFiles": "gTLzELtmiqZOM0dw9MPqYtFFBBIQwQ",
    "Username": "admin",
    "HeaderKey": null,
    "OAuthProvider": null,
    "OAuthId": null,
    "OAuthSecret": null,
    "OAuthUsePkce": false,
    "OAuthRecheckInterval": 12,
    "OAuthRestrictGroups": false,
    "OAuthRestrictGroupsText": "",
    "OAuthOnlyRegisteredUsers": false
  },
  "Port": ":53842",
  "ServerUrl": "http://10.89.62.2:53842/",
  "RedirectUrl": "https://github.com/Forceu/Gokapi/",
  "DataDir": "data",
  "DatabaseUrl": "sqlite://./data/gokapi.sqlite",
  "ConfigVersion": 22,
  "MaxFileSizeMB": 102400,
  "MaxMemory": 50,
  "ChunkSize": 45,
  "MaxParallelUploads": 3,
  "Encryption": {
    "Level": 0,
    "Cipher": null,
    "Salt": null,
    "Checksum": null,
    "ChecksumSalt": null
  },
  "UseSsl": false,
  "PicturesAlwaysLocal": false,
  "SaveIp": false,
  "IncludeFilename": false
}

2.1 端口与地址参数

参数	默认值	说明
Port	":53842"	服务监听端口，冒号前缀表示绑定全部网卡
ServerUrl	（向导填写）	生成分享链接的基地址，必须是客户端可达的地址；填错是"链接别人打不开"的头号原因
RedirectUrl	官方仓库页	访客下载完成后的跳转页，可改为企业门户
UseSsl	false	是否以 HTTPS 方式对外服务（服务端直连 TLS）；反代终结 TLS 时保持 false
DataDir	"data"	文件本体存储目录（相对运行目录）

2.2 认证参数

参数	说明
Authentication.Method	internal（内置账号）/ oauth2 / header / disabled 四选一，向导中对应 0-3
Username	管理员用户名
SaltAdmin / SaltFiles	管理员密码与分享口令的加盐哈希盐值，随安装随机生成，不可手工更换
HeaderKey	header 认证模式下受信任的请求头名称
OAuth*	OIDC 对接参数（Provider/ClientId/Secret/PKCE 等），oauth2 模式专用
OAuthRecheckInterval	OIDC 用户组复核间隔（小时）

2.3 存储与上传参数

参数	默认值	说明
MaxFileSizeMB	102400	单文件上限（默认 100 GB）
MaxMemory	50	上传时占用的内存缓冲比例（%），影响磁盘缓存阈值
ChunkSize	45	网页分块上传的块大小（MB），弱网环境可调小
MaxParallelUploads	3	单次上传的并行块数
DatabaseUrl	"sqlite://./data/gokapi.sqlite"	元数据库连接串，支持 sqlite:// 与 redis:// 两种前缀
PicturesAlwaysLocal	false	缩略图类小文件是否强制落本地（S3 模式下减少请求）

2.4 加密参数

Encryption.Level 是全配置最关键的字段，v2.2.4 提供 0-5 六级：

Level	含义	密钥位置	适用
0	不加密	—	内网/非敏感
1	服务端加密，密钥存服务器	config 内（Cipher 字段）	免密重启、防护落盘泄露
2	服务端加密，启动时输密码	内存	管理员每启必输密
3	端到端加密，密钥存服务器	config 内	浏览器端解密
4	端到端加密，启动时输密码	内存	同 2+3 叠加
5	端到端加密，密钥由浏览器持有	浏览器	最高安全，服务端无私钥

配套字段：Cipher（加密密钥密文）、Salt（派生盐）、Checksum/ChecksumSalt（密钥正确性校验）。Level 0 时均为 null。

2.5 其他参数

参数	说明
SaveIp	日志是否记录下载者 IP（合规自评后开启）
IncludeFilename	分享链接是否携带文件名
ConfigVersion	配置结构版本号（22），升级程序据此自动迁移

三、修改-验证实战

3.1 修改服务端口

编辑 config.json 的 Port 字段（例如改为 :53843），重启服务：

systemctl restart gokapi
ss -ltnp | grep 53843

实测输出：

LISTEN 0 4096 *:53843 users:(("gokapi",pid=3297,fd=6))

同时建议把 ServerUrl 同步修改，否则生成的分享链接仍指向旧端口。

3.2 切换加密等级（Level 0 → 1）

加密涉及密钥派生，通过 --reconfigure 向导切换（直接手改 JSON 会缺失 Checksum 校验）。停服后执行：

systemctl stop gokapi
gokapi --reconfigure

程序打印一组一次性凭据并打开向导，在 Encryption 区选择 Level 1 并设置加密密码，提交后实测输出：

Saving new files to local storage
Binding webserver to :53842
Webserver can be accessed at http://10.89.62.2:53842/admin

验证加密效果——上传一个 98 字节的明文文件，检查落盘内容：

find /opt/gokapi/data -type f ! -name "*.sqlite*" | head -1 | xargs stat -c "%s"

98 字节明文落盘为 114 字节（多出的 16 字节为 AES-GCM 认证标签），且内容为不可读密文；而通过分享链接下载时服务端透明解密，下载文件的 SHA-256 与原文件完全一致（实测 237df65a...774）。这就是 Level 1"密文落盘、明文交付"的行为边界。

继续切换到 Level 5（端到端加密）后，行为差异验证：上传返回的文件信息中 IsEndToEndEncrypted 与 RequiresClientSideDecryption 均为 true，且 UrlHotlink 变为空——E2E 文件不提供直链/热链，只能经浏览器解密页访问；服务端收到的字节即存储的字节（服务端无私钥）。

3.3 切换 S3 兼容存储

同样经 --reconfigure 向导，Storage 区选择"云存储"并填写 S3 参数（本文以一台自建 MinIO 为例，监听 9000 端口，预建桶 gokapi）：

项	示例值
Bucket	gokapi
Region	us-east-1
Access Key / Secret	minioadmin / minioadmin
Endpoint	http://minio.example.internal:9000

向导页内置连通性测试按钮，实测响应：

Test OK. WARNING: CORS settings do not allow encrypted downloads.

提交后服务重启，日志输出：

CORS settings of the cloud storage do not allow encrypted downloads. Please check the documentation!

配置落盘变化：DatabaseUrl 之外新增存储走向，PicturesAlwaysLocal 建议在 S3 模式下保持默认。验证数据真的落在对象存储——上传后列举桶内对象：

mc ls local/gokapi

e2e-nBX0DrNM4BM6gdJUU9oa 35 B

验证下载路径：客户端请求 downloadFile?id=...，实测服务端返回 307 Temporary Redirect，Location 为带签名的对象存储预签名 URL（X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=15...），跟随重定向下载得到完整文件（HTTP 200）。这里有一个高频坑：预签名 URL 的主机部分就是 Endpoint 配置值，必须保证客户端能解析并访问该主机名——如果 Endpoint 填了仅服务器内网可解析的地址，访客将下载失败；若客户端无法直连对象存储，可在向导存储区选择 proxy 模式（Gokapi 代理流量而非重定向）。

3.4 元数据库切换（SQLite → Redis）

多实例部署或需要外部化元数据时，把元数据迁到 Redis。Gokapi 内置迁移命令：

cd /opt/gokapi
gokapi migrate-database --source sqlite://./data/gokapi.sqlite \
  --destination redis://redis.internal:6379

实测输出：

Migrating SQLite database ./data/gokapi.sqlite to Redis database gokapi-2.2.4-redis:6379

验证迁移结果（Redis 侧）：

redis-cli dbsize
redis-cli --scan --count 100

7
apikey:wECzwsdl19hekpKcbfzFj8xSxpaLTy
dbversion
e2einfo:1
fmeta:7Ur6acSvHjQPMnd
userid_max
users:1

迁移完成后，将 DatabaseUrl 改为 redis://redis.internal:6379 并重启。注意两个实测细节：--source 必须带 sqlite:// 前缀（裸路径报 unsupported database type）；相对路径基于当前工作目录解析（裸文件名报 open gokapi.sqlite: no such file or directory）。

四、环境变量与启动参数

少量行为可用环境变量覆盖（实测 GOKAPI_PORT=53998 启动时，向导提示变为 Please open http://10.89.62.2:53998/setup），常用：

变量	作用
GOKAPI_PORT	覆盖向导/服务端口
GOKAPI_CONFIG_DIR / GOKAPI_DATA_DIR	重定向配置与数据目录
GOKAPI_AWS_BUCKET / REGION / KEY / SECRET / URL	非交互式提供 S3 凭据（避免明文落配置文件）

完整启动参数矩阵见同专栏 CLI 命令篇。

五、常见配置排障

现象	原因与处理
手改 Encryption 后服务报密钥校验失败	加密字段有 Checksum 闭环，必须经 `--reconfigure` 修改
S3 连通测试失败	依次核对 Endpoint 可达性、Access Key/Secret、桶已预建
加密下载报 CORS 错	对象存储未配置跨域响应头；或存储区改用 proxy 模式
迁移命令报 unsupported database type	source/destination 必须带 sqlite:// / redis:// 前缀
切端口后分享链接仍旧端口	Port 与 ServerUrl 需同时修改

六、参考链接

官方配置文档：https://gokapi.readthedocs.io/en/latest/configuration.html
加密说明：https://gokapi.readthedocs.io/en/latest/encryption.html
专栏系列：《Gokapi 2.2.4 介绍与选型指南》《Ubuntu 22.04 安装 Gokapi 2.2.4 指南》《Gokapi 2.2.4 常用 CLI 命令详解》