Gokapi 2.2.4 介绍与选型指南
Gokapi 轻量一次性文件分享服务器全解：核心架构、过期/一次性/E2E 加密/S3 兼容存储/REST API 特性拆解，与 PsiTransfer、Plik、Sharry、Uguu、copyparty 的量化选型对比。
Gokapi 2.2.4 介绍与选型指南
目标：读完本篇，你将能回答三个问题——Gokapi 是什么、它能解决什么问题、以及在同类一次性文件分享工具（PsiTransfer、Plik、Sharry、Uguu、copyparty）中如何选型。全文数据均来自 Gokapi 官方仓库与文档的联网溯源（检索日期：2026-10-26），不含本地实测结论；需要动手部署的读者可直接跳转同专栏的安装篇与配置篇。
一、软件概述
1.1 项目定位
Gokapi 是一个由 Go 语言编写的轻量级一次性文件分享服务器（one-time file sharing server），主打"给文件生成带过期策略的分享链接"，常被用作 Firefox Send 的自托管替代方案。项目由 Forceu 维护，采用 AGPL-3.0 开源协议（来源：GitHub 仓库 README，检索日期 2026-10-26）。
版本检索（检索日期 2026-10-26，来源：GitHub Releases）：
| 项目 | 值 |
|---|---|
| 最新稳定版本 | v2.2.4 |
| GitHub 星数 | 约 2.9k（shields.io 实时徽章） |
| 开源协议 | AGPL-3.0 |
| 实现语言 | Go |
| 官方支持平台 | Linux、macOS、Windows |
| 官方文档站 | https://gokapi.readthedocs.io |
1.2 名词解释
- 一次性分享链接：链接被下载次数达到设定值或超过有效期后立即失效，服务端自动删除关联文件，避免"链接外泄后文件被无限扩散"。
- 端到端加密（E2EE，End-to-End Encryption）：文件在上传方完成加密，服务端仅存储密文、不具备解密能力，解密密钥只存在于持有密码的浏览器端。
- 对象存储（S3，Simple Storage Service）：AWS 推出的对象存储接口规范，现已形成事实标准；MinIO、Backblaze B2 等均提供 S3 兼容接口。
- OIDC（OpenID Connect）：基于 OAuth 2.0 的身份认证协议，可对接 Authelia、Keycloak 等统一身份平台。
1.3 版本演进要点
Gokapi v2 相比 v1 有两处影响使用的结构性变化，选型与部署前必须知晓：
- 默认服务端口变更为 53842（v1.x 时代为 5384），首次启动的安装向导监听该端口；
- 管理界面改为"会话 + 短期令牌"双重鉴权，管理页的文件操作需先换取带权限位的令牌，公开 REST API 的鉴权方式也随之调整。
二、核心架构
2.1 组件构成
Gokapi 采用典型的单二进制分层架构，无需外部数据库即可运行：
| 层次 | 组件 | 说明 |
|---|---|---|
| 接入层 | 内置 Go Web 服务器 | 同时承载管理后台、下载页、REST API |
| 业务层 | 分享/加密/限次/过期引擎 | 下载计数、过期清理、链接失效判定 |
| 存储层 | 本地文件系统 或 S3 兼容存储 | 通过预签名 URL 或代理方式读写 |
| 元数据层 | SQLite（默认）或 Redis | 存储文件元数据、用户、会话、API 密钥 |
这种"单二进制 + SQLite + 本地盘"的最小组合，使 Gokapi 的最低资源需求仅为 1 核 CPU、256 MB 内存、100 MB 存储（来源：官方 README System Requirements，检索日期 2026-10-26）。
2.2 分享生命周期
一次典型的 Gokapi 分享流程为：上传文件 → 生成分享链接（下载页 URL 与直接下载 URL 两种形态）→ 访客访问下载页 → 下载计数递减 → 计数归零或到达过期时间后，文件本体与元数据被清理，原链接变为错误页。整个链条无需注册账号即可面向访客完成，管理员仅在上传端需要认证。
三、功能特性
3.1 特性清单
以下特性列表来自官方仓库 README（检索日期 2026-10-26）：
- 过期分享：按下载次数或天数自动失效并删除文件；
- 用户管理与角色权限：细粒度权限控制，可限制仅注册用户上传；
- 文件请求（File Requests）：生成一个外部可上传的 URL，访客上传的文件仅该 URL 创建者可见；
- 文件去重：内容相同的文件在服务端仅占一份空间；
- 云存储支持：AWS S3 或 S3 兼容服务（如 Backblaze B2）；
- 内置加密：包含端到端加密上传；
- OIDC 支持：对接 Authelia、Keycloak 等身份提供方；
- REST API：面向自动化与系统集成的完整接口；
- 可定制 UI：支持自定义 CSS 与 JavaScript。
3.2 加密体系
Gokapi v2 的安装向导提供 6 个加密等级（编号 0-5），覆盖三类形态：不加密；服务端加密（密钥保存在服务器，下载时透明解密）；端到端加密（服务端只存密文，下载时由浏览器 JavaScript 解密）。其中端到端模式下，文件的直接下载与热链（hotlink）能力被禁用，只能通过带解密的下载页访问。
3.3 管理与自动化能力
- 管理后台：上传、改期、删除、生成上传请求、管理用户与 API 密钥；
- REST API：文件列表/详情/修改/删除、密钥管理、会话令牌；
- 命令行工具：安装为系统服务、迁移数据库（SQLite 与 Redis 互转）、重置管理员密码等维护能力；
- 反向代理友好：内置 WebSocket 与 HTTPS 透传配置项，可置于 Nginx/Caddy 之后。
四、快速开始
以下为官方仓库 README「Getting Started」与文档站的公开部署口径（检索日期 2026-10-26），供选型评估；完整的从零部署、系统服务托管与排障记录，见同专栏安装篇。
官方提供预编译的 Linux 发行包，最小启动路径为：
- 从 GitHub Releases 下载对应架构的压缩包（如
gokapi-2.2.4_linux-amd64.zip），解压得到单个gokapi可执行文件； - 将其安装到系统路径（例如
/usr/local/bin/gokapi）； - 以服务方式或直接运行
gokapi，首次启动会自动进入安装向导； - 在向导中设定管理端口、管理员账号密码、存储类型与加密等级；
- 向导保存后服务即进入运行状态，浏览器访问管理地址开始上传分享。
v2.2.4 默认监听端口为 53842，首次部署时放行防火墙该端口即可访问向导与后台。
五、适用场景与限制
5.1 典型适用场景
| 场景 | 适配理由 |
|---|---|
| 运维/开发团队对外交付补丁、安装包 | 一次性链接 + 次数限制，防外传 |
| 客户索取日志、抓包等"回传文件" | 文件请求功能提供访客上传入口 |
| 合规敏感文件外发 | 端到端加密，服务端无私钥 |
| 内部工具集成 | REST API 自动化生成/回收分享 |
5.2 已知限制
- 单机定位：无内置集群与多节点同步，容量受单机磁盘或所接对象存储约束；
- 管理侧认证粒度较细但角色模型简单，不适合作为企业级网盘使用；
- AGPL-3.0 协议对二次开发后的网络服务场景有开源义务，商业闭源集成需评估合规。
六、同类选型对比
6.1 候选产品一览
选型池选择与 Gokapi 同赛道（临时/一次性文件分享、可自托管）的五个代表性项目。以下信息均为各项目官方仓库公开描述（检索日期 2026-10-26）：
| 项目 | 语言 | 协议 | 定位一句话 |
|---|---|---|---|
| Gokapi 2.2.4 | Go | AGPL-3.0 | 一次性文件分享服务器（Firefox Send 替代） |
| PsiTransfer 2.x | Node.js | MIT | 带大文件流式上传的简单分享服务 |
| Plik 1.x | Go | Apache-2.0 | 可扩展的临时文件上传平台（对象存储多后端） |
| Sharry 2.x | Scala | GPL-3.0 | 面向"我给一组文件、你凭口令来取"的分享服务 |
| Uguu 1.x | PHP | MIT | 极简临时文件托管（小时级自动过期） |
| copyparty 1.x | Python | MIT | 多协议媒体服务器，附带上传与分享能力 |
6.2 一次性分享特性矩阵
矩阵依据为各项目官方文档/README 公开特性（检索日期 2026-10-26），"✓/✗" 表示官方明确具备/未提供：
| 特性 | Gokapi | PsiTransfer | Plik | Sharry | Uguu | copyparty |
|---|---|---|---|---|---|---|
| 一次性下载链接（用后即焚） | ✓ | ✓ | ✓ | ✗（按时间过期） | ✗（按时间过期） | ✓（可配置） |
| 按下载次数过期 | ✓ | ✓ | ✓ | ✗ | ✗ | ✓ |
| 按天数过期 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 链接密码保护 | ✓ | ✓ | ✓ | ✓ | ✗ | ✓ |
| 端到端加密（服务端无私钥） | ✓ | ✗ | ✓（客户端加密） | ✗ | ✗ | ✓（可选） |
| 服务端存储可外接 S3 | ✓ | ✗（本地/流式） | ✓ | ✗（本地盘） | ✗ | ✗（本地盘为主） |
| 访客上传（文件请求/公开上传页） | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| 用户体系与角色权限 | ✓ | ✗ | ✗（匿名为主） | ✓ | ✗ | ✓（多用户目录） |
| REST API | ✓ | 有限 | ✓ | ✓ | ✗（仅 CLI） | ✓ |
| 内置数据库（无需外部依赖） | ✓（SQLite） | ✓（SQLite） | ✓（SQLite） | ✓（内置 H2） | ✓（无数据库） | ✓ |
| 单文件部署（免运行时） | ✓（Go 二进制） | ✗（需 Node.js） | ✓（Go 二进制） | ✗（需 JVM） | ✗（需 PHP） | ✗（需 Python） |
| 最低内存需求 | 256 MB | ~512 MB（Node.js） | 128 MB 级 | 1 GB 级（JVM） | 极低 | 极低 |
6.3 选型结论
- 追求"链接用后即焚 + E2E + S3 归档 + API 自动化"的均衡：Gokapi 是唯一六项全占的候选，且单二进制、256 MB 内存即可跑，运维面最窄；
- 只需要极简的一次性大文件中转、无用户诉求：PsiTransfer 的流式上传对超大文件更友好，但无服务端加密与 S3 外接；
- 已有对象存储、想把临时文件全部落到 S3：Plik 的多后端扩展性更强，但缺少用户体系与"文件请求"这类收件场景；
- 重"口令取件"的协作式分享：Sharry 体验完整，但一次性下载语义弱（过期以时间为主）且 JVM 栈偏重；
- 纯临时中转、几小时后自动清空的匿名场景：Uguu 最轻，但无加密、无账号、无 API；
- 同时要媒体库 + 上传分享的家用服务器：copyparty 功能最杂糅，分享是其能力子集，反着选型（要分享为主）不如 Gokapi 专注。