Gokapi 2.2.4 常用 CLI 命令详解

目标：用一条手册页的篇幅掌握 Gokapi 2.2.4 的命令行体系——服务参数矩阵、五类维护命令的实测行为，以及 REST API 的 curl 全流程闭环（密钥鉴权 → 列表 → 上传 → 改删）。本文承接安装篇与配置篇的同一实例（服务器 10.89.62.2:53842，管理员 admin/q1w2e3r4）。

一、命令总览与帮助体系

1.1 帮助输出全解

gokapi --help

实测输出：

Usage:
gokapi [application arguments]
Gokapi will run as a service if no arguments are passed
If environment variables are passed, they will override the values in config
or use default value if not set

Application arguments:
--version
        Prints the version number and exits
--help
        Prints this help message and exits
--config-dir [PATH]
        Sets the folder for storing the gokapi.conf
        Default: ./config
--config [PATH]
        Sets the path to the gokapi.conf
        Default: ./config/gokapi.conf
--data [PATH]
        Sets the folder for storing the uploaded files and the sqlite database
        Default: ./data
--port [PORT]
        Sets the port for the setup webserver
        Default: 53842
--install-service
        Installs Gokapi as a system service
--uninstall-service
        Uninstalls the Gokapi system service
--reconfigure
        Run the setup where settings can be changed
--create-ssl
        Generates a self-signed SSL certificate
--deployment-password [string]
        Sets a new password. This should only be used for non-interactive deployment
migrate-database
        Migrates database from one database to another. Use --source and --destination
        arguments, which require a database URL.

1.2 服务参数矩阵

参数	作用	典型场景
（无参数）	前台运行服务（无配置则先进向导）	手动运行/systemd ExecStart
--version	输出版本并退出	升级前后核对
--help	输出帮助	查参数
--config-dir PATH	指定配置目录（默认 ./config）	多实例/自定义布局
--config PATH	指定配置文件全路径	精细控制
--data PATH	指定数据目录（默认 ./data）	数据盘分离
--port PORT	指定setup 向导端口	向导端口冲突
--install-service	安装系统服务	托管
--uninstall-service	卸载系统服务	下线
--reconfigure	重开安装向导改配置	换端口/加密/存储
--create-ssl	生成自签证书	无反代时启用 HTTPS
--deployment-password PW	重置管理员密码	忘记密码/自动化部署
migrate-database	元数据库迁移	SQLite→Redis

注意 --port 语义：它改的是 setup 向导端口，而非长期服务端口（服务端口在 config.json 的 Port 字段，见配置篇）。

二、部署与维护命令实测

2.1 --install-service / --uninstall-service

gokapi --install-service

两条安全约束实测：

Installing Gokapi as a service...
WARNING! Could not determine user invoking sudo.
Could not determine username other than root. Not running service as root.

以 root 运行会被拒绝（Gokapi 不允许服务以 root 身份执行）；以普通用户执行但探测不到 sudo 提权时则报 This feature requires root privileges.。在标准 sudo 环境的真实服务器上，普通用户执行即可完成安装（生成 /etc/systemd/system/gokapi.service 并 enable）；受控环境下更推荐安装篇 5.2 节的手动 unit 文件方案。卸载使用 gokapi --uninstall-service。

2.2 --reconfigure

修改端口、加密等级、存储后端等核心配置的官方入口。执行后服务暂停，进入向导模式：

systemctl stop gokapi
gokapi --reconfigure

Gokapi v2.2.4 starting
Please use the following credentials for the initial setup:
Username: CS3V2z
Password: IY3N5sXDOU
Please open http://10.89.62.2:53842/setup to setup Gokapi.

每次执行 --reconfigure 都会生成一组全新的一次性凭据（上例 CS3V2z / IY3N5sXDOU），凭据仅在本次向导期间有效——这是防止运行中的服务被旁路重配置的保护机制，务必从日志抄录。在向导中完成修改并提交后，服务自动以新配置重启。完整修改-验证过程见配置篇第三节。

2.3 --create-ssl

生成自签 TLS 证书，适合没有反向代理的小型内网部署：

gokapi --create-ssl

若此时服务仍在运行，实测报端口冲突：

This port is already in use. Use parameter -p or env variable GOKAPI_PORT to change the port.
Setup Webserver: listen tcp :53842: bind: address already in use

先停服务（或按提示换端口）再执行。生成后配合配置 UseSsl: true 与重启生效。

2.4 --deployment-password：密码重置

管理员密码遗忘时的官方重置手段（v1 时代的 --reset-password 在 v2 已移除，见 2.6 节）：

gokapi --deployment-password Test12345678

命令设置新密码后服务随即启动。验证：旧密码 q1w2e3r4 登录返回错误页，新密码登录返回 HTTP 200。该命令同样拒绝 root 身份执行（与 --install-service 同一套安全检查），请以普通运行用户执行。

2.5 migrate-database

元数据库迁移（SQLite 与 Redis 互转），实测与验证细节见配置篇 3.4 节。要点回顾：

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

2.6 v1 旧命令的替代方案

对从 v1 升级而来的读者，以下两个旧命令在 v2.2.4 中已不存在：

gokapi --decrypt
gokapi --reset-password

实测输出（两条一致）：

2026/10/26 08:36:20 flag provided but not defined: -decrypt
Gokapi v2.2.4
Build Date: Sun Mar 15 08:27:51 UTC 2026
Go Version: go1.26.1
Git Commit: 9a4b289c

替代对应关系：

v1 命令	v2.2.4 替代
--reset-password	--deployment-password（免交互）或 --reconfigure 向导
--decrypt	已移除；加密等级与密钥管理统一收敛到 --reconfigure 向导与 config.json

三、REST API 实战

3.1 API 密钥创建与鉴权

API 密钥在管理后台 API Settings 页创建。实测创建请求（需先以管理员会话换取带 PERM_API_MOD 权限位的短期令牌）：

curl -s -X POST http://10.89.62.2:53842/api/auth/create \
  -H "Content-Type: application/json" \
  -H "apikey: <会话令牌>" -H "basicPermissions: true"

实测返回：

{
  "idOrUuid": "wECzwsdl19hekpKcbfzFj8xSxpaLTy",
  "publicId": "k6qIxGWclMQs3oicCDYJSz0fGrgbwQIeLsT",
  "lastUsed": "0001-01-01T00:00:00Z",
  "permissions": 23
}

鉴权要点（实测踩坑）：请求头 apikey 的取值是返回体里的 idOrUuid 字段（wECzwsdl19hekpKcbfzFj8xSxpaLTy）——使用 publicId 会得到 401。permissions=23 为位掩码（1=查看列表、2=上传、4=编辑、16=替换，即"基础权限"组合）。

3.2 文件列表与详情

KEY=wECzwsdl19hekpKcbfzFj8xSxpaLTy
curl -s -H "apikey: $KEY" "http://10.89.62.2:53842/api/files/list"

实测返回文件对象数组（节选）：

[{
  "Id": "xorSW0Ax1lTy9NJ",
  "Name": "s3-test.bin",
  "Size": "35 B",
  "DownloadsRemaining": 98,
  "DownloadCount": 2,
  "ExpireAtString": "2026-11-09 08:27:26",
  "UrlDownload": "http://10.89.62.2:53842/downloadFile?id=xorSW0Ax1lTy9NJ",
  "IsEndToEndEncrypted": false,
  "RequiresClientSideDecryption": false,
  "IsEncrypted": true,
  "UnlimitedDownloads": false,
  "UnlimitedTime": false,
  "PasswordHash": "",
  "IsPasswordRequired": false
}]

单个文件详情：GET /api/files/list/{id}（如 .../list/xorSW0Ax1lTy9NJ），返回同结构对象。注意 URL 尾部斜杠有语义：/api/files/list/ 会被当作详情查询而报 File not found，列表请求不要带尾斜杠。

3.3 上传（分块协议）

管理端上传由两个接口组成：分块传输 + 完成合并。上传接口仅接受管理员会话，因此先用会话换取上传令牌：

TOKEN=$(curl -s -b <会话Cookie> -X POST \
  -H "permission: PERM_UPLOAD" http://10.89.62.2:53842/auth/token | grep -oE '"key":"[^"]+"' | cut -d'"' -f4)

实测返回：

{"key":"mLd0KxwUuIf4MrwM4diTw040x36VGd","expiry":"2026-10-26T09:22:12.511086398Z"}

第一步，分块传输（大文件按块循环，参数与网页端分块协议一致）：

curl -s -X POST http://10.89.62.2:53842/uploadChunk -b <会话Cookie> \
  -F "file=@demo-report.pdf" \
  -F "dzuuid=8f8f9a1e-3f0c-4c9d-8a1b-2e3d4f5a6b7c" \
  -F "dzchunkindex=0" -F "dztotalfilesize=3145728" \
  -F "dzchunksize=10485760" -F "dztotalchunkcount=1" -F "dzchunkbyteoffset=0" \
  -F "allowedDownloads=14" -F "expiryDays=14"

{"result":"OK"}

第二步，合并入库（用短期上传令牌）：

curl -s -X POST http://10.89.62.2:53842/api/chunk/complete \
  -H "apikey: $TOKEN" -H "uuid: 8f8f9a1e-3f0c-4c9d-8a1b-2e3d4f5a6b7c" \
  -H "filename: base64:$(echo -n demo-report.pdf | base64 -w0)" \
  -H "filesize: 3145728" -H "realsize: 3145728" -H "contenttype: application/pdf" \
  -H "allowedDownloads: 14" -H "expiryDays: 14" \
  -H "password: " -H "isE2E: false" -H "nonblocking: false"

实测返回关键片段：

{
  "Id": "7Ur6acSvHjQPMnd",
  "UrlDownload": "http://10.89.62.2:53842/d?id=7Ur6acSvHjQPMnd",
  "DownloadsRemaining": 14,
  "ExpireAtString": "2026-11-09 08:12:58"
}

UrlDownload 即分享链接，可直接投递给访客。文件名按 base64:<Base64串> 格式传递以支持中文等非 ASCII 字符。

3.4 修改与删除

修改（PUT + 全部参数走请求头）：

curl -s -X PUT http://10.89.62.2:53842/api/files/modify \
  -H "apikey: $KEY" -H "Content-Type: application/json" \
  -H "id: xorSW0Ax1lTy9NJ" \
  -H "allowedDownloads: 10" \
  -H "expiryTimestamp: 1793364897" \
  -H "password: "

实测验证：再次查询详情，DownloadsRemaining 由 98 变为 10，ExpireAtString 变为 2026-11-02 08:34:57——剩余次数与过期时间均按请求生效。注意过期时间用 Unix 秒（expiryTimestamp），而不是天数。

删除（POST + 请求头传 id）：

curl -s -X POST http://10.89.62.2:53842/api/files/delete \
  -H "apikey: $KEY" -H "id: 7Ur6acSvHjQPMnd"

实测：响应为空（HTTP 200），随后的列表请求中该文件已消失。删除同时清理服务端的文件本体与缩略图缓存。

3.5 鉴权错误码对照

实测两组典型失败：

请求	实测响应
`apikey` 缺失或为错值（如用 publicId）	`{"error":"Unauthorized","ErrorCode":2}`（HTTP 401）
分块上传接口携带 API 密钥而非会话	`{"error":"Not authenticated"}`（该接口仅限管理员会话）
详情接口 URL 带尾斜杠且无 id	`{"error":"File not found","ErrorCode":3}`
删除/修改缺 `id` 请求头	`{"error":"header id is required"}`

排障口诀：401 先查 key 是否用错字段；参数缺失看错误文案是否点名 header；ErrorCode 数值可作为日志告警的分类键。

四、常用排障速查

现象	处理
--install-service 拒绝执行	服务不允许 root 身份，切普通用户并保证 sudo 可用
--reconfigure 打不开向导	从启动日志抄录本次一次性凭据；端口冲突时加 `--port`
旧命令 --reset-password/--decrypt 报 not defined	v2 已移除，按 2.6 节替代
API 401 Unauthorized	apikey 用 idOrUuid 而非 publicId
API 删除/修改不生效	确认 id 放在请求头（v2 新协议），PUT/POST 方法选择正确
上传 404	分块上传路径是 /uploadChunk（根路径），不是 /admin/uploadChunk

五、参考链接

官方 API 文档：https://gokapi.readthedocs.io/en/latest/api.html
命令行说明：https://gokapi.readthedocs.io/en/latest/commandline.html
专栏系列：《Gokapi 2.2.4 介绍与选型指南》《Ubuntu 22.04 安装 Gokapi 2.2.4 指南》《Gokapi 2.2.4 配置参数详解》