Ubuntu 22.04 安装 Gokapi 2.2.4 指南

目标：在一台 Ubuntu 22.04 服务器上完成 Gokapi 2.2.4 的从零部署——下载官方发行包、跑通首次安装向导、产出第一个一次性分享链接并验证其"用后即焚"行为，最后将 Gokapi 托管为系统服务。本文所有命令与输出均来自真实服务器的逐步实测（版本检索日期：2026-10-26）。

一、环境准备

1.1 系统与软件信息

Gokapi 官方最低要求为 1 核 CPU、256 MB 内存、100 MB 磁盘外加文件存储空间，Ubuntu 22.04 默认软件源无需任何额外依赖，Go 静态编译的单二进制开箱即用。

1.2 网络与防火墙

Gokapi v2.2.4 的默认端口是 53842（注意：v1.x 时代默认端口为 5384，网上旧教程普遍写的 5384 在 v2 上会连不通向导，这是首次部署最常见的坑）。放行端口：

sudo ufw allow 53842/tcp
sudo ufw reload

如果部署在内网且暂时未启用 ufw，可先跳过此步，部署完成后统一检查。

二、安装 Gokapi

2.1 下载发行包

从 GitHub Releases 下载官方预编译包：

cd /tmp
curl -sL -o gokapi-2.2.4_linux-amd64.zip \
  https://github.com/Forceu/Gokapi/releases/download/v2.2.4/gokapi-2.2.4_linux-amd64.zip
ls -la gokapi-2.2.4_linux-amd64.zip

实测输出：

-rw-r--r-- 1 root root 16133847 Oct 26 09:56 gokapi-2.2.4_linux-amd64.zip

若服务器访问 GitHub 较慢，可为 curl 配置 HTTP 代理加速（如 curl -x http://代理地址:端口 ...），或先行本地下载再上传至服务器。

2.2 解压并安装二进制

发行包内只有一个 gokapi 可执行文件，解压后安装到系统路径：

cd /tmp
unzip -o gokapi-2.2.4_linux-amd64.zip
install -m 755 gokapi /usr/local/bin/gokapi

2.3 验证版本

gokapi --version

实测输出：

Gokapi v2.2.4 (build 2026-03-15)
Build Date: Sun Mar 15 08:27:51 UTC 2026
Go Version: go1.26.1
Git Commit: 9a4b289c

三、首次启动与安装向导

3.1 启动与向导入口

首次直接运行 gokapi，程序检测到无配置文件，自动进入安装向导模式：

cd /opt/gokapi
gokapi

实测输出：

Gokapi v2.2.4 starting
Creating new configuration file
Please use the following credentials for the initial setup:
Username: EPWlVa
Password: jRxmDevLsE
Please open http://10.89.62.2:53842/setup to setup Gokapi.

重要说明：

1. 向导地址实际监听 53842 端口（与配置的默认服务端口一致），首次启动日志里提示的地址即向导入口；
2. 首次启动会生成一组一次性初始凭据（如上例 EPWlVa / jRxmDevLsE），浏览器打开向导时需要先输入这组凭据，防止向导页面在配置完成前被他人篡改。请把这组凭据记录下来；
3. 以后每次执行 gokapi --reconfigure 重新进入向导，也会生成一组新的一次性凭据。

3.2 向导配置项

浏览器打开 http://10.89.62.2:53842/setup，输入初始凭据后进入向导。向导为单页表单，按区块逐项确认：

数据库区：

常规设置区：

身份认证区： 认证方式选择"用户名/密码"，设置管理员账号：

存储区： 选择"本地存储"（local）。S3 兼容存储的接入方法见配置篇第几节对应说明。

加密区： 首次部署先选择 Level 0（不加密）快速跑通；加密等级的完整说明与切换方法见配置篇。向导提供 0-5 六级加密，其中 1/2 为服务端加密，3/4/5 涉及端到端加密。

确认无误后点击向导末尾的提交按钮。

3.3 完成安装

提交后程序自动落盘配置并切换到服务模式，服务端日志实测输出：

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

此时配置文件与数据库已生成在工作目录下（本文为 /opt/gokapi/）：

ls -la /opt/gokapi /opt/gokapi/config /opt/gokapi/data

实测输出：

/opt/gokapi/:
total 20
drwxr-xr-x 5 root root 4096 Oct 26 08:41 .
drwxr-xr-x 5 root root 4096 Oct 26 08:39 config
drwxr-xr-x 2 root root 4096 Oct 26 08:41 data

/opt/gokapi/config/:
total 24
-rw------- 1 root root 1438 Oct 26 08:41 config.json

/opt/gokapi/data/:
total 40
-rw-r--r-- 1 root root 32768 Oct 26 08:41 gokapi.sqlite

四、首个分享与链接验证

4.1 登录后台

浏览器打开 http://10.89.62.2:53842/admin，使用 admin / q1w2e3r4 登录。服务端会先校验登录表单内置的 CSRF 令牌，会话通过 session_token Cookie 维持（HTTPOnly）。登录成功即进入管理后台的文件列表页。

4.2 上传文件

点击右上角 Upload 进入上传页，将测试文件拖入虚线框（或点击选择文件），页面下方可按需调整：

• Allowed downloads：允许下载的次数（默认 1，本次演示设为 14）；
• Expiry in days：有效天数（默认 14）；
• Password：可选下载口令。

点击 Upload 开始上传。Gokapi 的网页上传采用分块上传协议：文件被切成 45 MB 左右的块依次 POST 到服务端，上传完成时再调用一次完成接口合并入库。分块机制天然支持大文件断点续传。

上传完成，服务端日志输出：

Upload complete

4.3 提取一次性链接

回到管理后台文件列表，点击该文件右侧菜单中的 Copy URL，得到两种形态的链接：

下载页：http://10.89.62.2:53842/d?id=7Ur6acSvHjQPMnd
直  链：http://10.89.62.2:53842/downloadFile?id=7Ur6acSvHjQPMnd

其中 d?id= 指向一个带"Download"确认按钮的网页，适合发给人类用户；downloadFile?id= 直接触发下载，适合放进脚本或 README。二者共享同一个下载配额。

4.4 验证次数限制与失效

对直链连续访问，观察配额递减与失效行为：

curl -s -o /dev/null -w "%{http_code} %{size_download}\n" \
  "http://10.89.62.2:53842/downloadFile?id=7Ur6acSvHjQPMnd"

实测：前两次均返回 200 3145728（完整 3 MB 文件），管理页该文件的剩余次数从 14 递减到 12。

将一个文件的上传配额设为 1 再验证"用后即焚"：

# 第 1 次下载
curl -s -o /dev/null -w "%{http_code} %{size_download}\n" \
  "http://10.89.62.2:53842/downloadFile?id=sxfTA96j62m5a0w"
# 第 2 次下载
curl -s "http://10.89.62.2:53842/downloadFile?id=sxfTA96j62m5a0w"

实测输出：

200 65536
<meta http-equiv="Refresh" content="0; URL=./error">

第 2 次访问只返回一个 78 字节的跳转页，重定向到错误提示页（提示链接已失效），文件本体已被服务端删除。这就是 Gokapi 的核心交付物——一次性分享链接。

过期机制同理：到达向导设定的有效天数后（元数据里的过期时间戳早于当前时间），访问同样落入错误页。

五、系统服务托管（systemd）

5.1 内置命令实测

Gokapi 内置了服务安装命令：

gokapi --install-service

该命令会生成 /etc/systemd/system/gokapi.service 并执行 daemon-reload 与 enable。需要特别注意其安全约束——Gokapi 拒绝以 root 身份运行服务，实测行为：

• 以 root 直接执行时，输出 Could not determine username other than root. Not running service as root. 后中止；
• 以普通用户执行但无法探测到可用 sudo 时，输出 This feature requires root privileges. 后中止。

因此建议使用 5.2 节的手动方式，行为完全透明可控。

5.2 手动 unit 文件方案

创建运行用户并授权数据目录：

useradd -r -s /usr/sbin/nologin gokapi
mkdir -p /opt/gokapi
chown -R gokapi:gokapi /opt/gokapi

写入 /etc/systemd/system/gokapi.service：

[Unit]
Description=Gokapi File Sharing Server
After=network.target

[Service]
Type=simple
User=gokapi
Group=gokapi
WorkingDirectory=/opt/gokapi
ExecStart=/usr/local/bin/gokapi
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

启用并启动：

systemctl daemon-reload
systemctl enable --now gokapi
systemctl status gokapi --no-pager

WorkingDirectory 决定配置与数据的落盘位置（config/ 与 data/ 子目录），务必与迁移前的目录一致。注意：切换运行用户后，需保证原数据目录对新用户可读写，否则服务会因无法打开 SQLite 库而启动失败。

六、常见问题排障

七、参考链接

• 官方安装文档：https://gokapi.readthedocs.io/en/latest/setup.html
• Releases 下载：https://github.com/Forceu/Gokapi/releases
• 专栏系列：《Gokapi 2.2.4 介绍与选型指南》《Gokapi 2.2.4 配置参数详解》《Gokapi 2.2.4 常用 CLI 命令详解》