Ubuntu 22.04 安装 Wakapi 2.18.2 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Wakapi 2.18.2 编码时间追踪服务，完成 systemd 托管、账号注册与 API 验证。本文已在 Ubuntu 22.04.5 LTS（x86_64）实测通过，Wakapi 以 SQLite 为默认存储、监听 3000 端口。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
软件版本：Wakapi 2.18.2（2026-10-14 发布，GitHub Releases 实查）
安装路径：/opt/wakapi/（二进制 + config.yml）
运行用户：wakapi（系统用户，无登录 shell）
默认存储：SQLite（/opt/wakapi/wakapi_db.db，零外部依赖）
监听地址：0.0.0.0:3000（IPv4；IPv6 按后文排障说明关闭）
下载渠道实测：GitHub Releases 官方源直连可用（实测约 18 秒完成 15 MB 下载）；Go 模块代理 proxy.golang.org 实测不可直连，源码编译方案需走 Go 模块镜像或网络代理（见「三、方案 B」）

二、前置条件

一台可联网的 Ubuntu 22.04 服务器（root 或可 sudo 的账号）；
磁盘预留 ≥ 200 MB（二进制约 40 MB，SQLite 数据随使用增长）；
端口 3000 未被占用（可用 ss -ltn | grep :3000 确认）；
若走源码编译方案：额外需要 Git 与 Go 1.25+ 工具链（下文给出安装步骤）。

三、版本选型说明

渠道	版本	说明
GitHub Releases 二进制（本文方案 A）	2.18.2	官方预编译单二进制，解压即用，版本号内嵌
`go install` 源码编译（本文方案 B）	2.18.2	需 Go 工具链，`--version` 输出为 `dev`（官方构建时才注入版本号）
官方托管 wakapi.dev	持续更新	零运维，数据托管在官方
官方发布镜像 ghcr.io/muety/wakapi	2.18.2	见本专栏 Compose 部署篇

💡 技术拓展：「编码时间追踪后端」还有 WakaTime 官方 SaaS、ActivityWatch 等路线，Wakapi 的核心差异是 MIT 开源 + 数据自有 + 复用 WakaTime 客户端插件生态；量化选型对比见本专栏《Wakapi 介绍与选型指南》。

四、方案 A：官方二进制在线安装（推荐）

本节从下载、校验到 systemd 托管完整走一遍，全程实测回显。

4.1 安装基础工具

apt-get update
apt-get install -y curl unzip ca-certificates

实测回显（节选）：

0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

4.2 下载官方二进制包

cd /root
curl -fsSL -o wakapi_linux_amd64.zip \
  https://github.com/muety/wakapi/releases/download/2.18.2/wakapi_linux_amd64.zip

实测下载耗时约 18 秒（15 MB）。官方源直连可用，无需镜像。

4.3 校验 SHA256

Releases 页公布的 wakapi_linux_amd64.zip 校验值为 a64e98f0a99ae4dd625ed3bff5b98e3b21130d2adc04184bfbbe35f21049273b，实测：

sha256sum wakapi_linux_amd64.zip

实测回显：

a64e98f0a99ae4dd625ed3bff5b98e3b21130d2adc04184bfbbe35f21049273b  wakapi_linux_amd64.zip

与官方一致，包完整可信。

4.4 解压并安装到 /opt/wakapi

zip 内为平铺结构（wakapi 二进制 + 默认 config.yml）：

unzip -o wakapi_linux_amd64.zip
mkdir -p /opt/wakapi
mv wakapi /opt/wakapi/wakapi
mv config.yml /opt/wakapi/config.yml
chmod +x /opt/wakapi/wakapi
/opt/wakapi/wakapi --version

实测回显：

Archive:  wakapi_linux_amd64.zip
  inflating: config.yml              
  inflating: wakapi                  
2.18.2

版本号 2.18.2 确认无误。Wakapi 的命令行参数非常精简（这是它把能力都放在配置文件与 API 上的设计）：

/opt/wakapi/wakapi --help

实测回显：

Usage of /opt/wakapi/wakapi:
  -config string
    	config file location (default "config.yml")
  -version
    	print version

4.5 调整配置（对外提供服务）

编辑 /opt/wakapi/config.yml，改动三处（其余保持默认，逐参数详解见《Wakapi 2.18.2 配置参数详解》）：

server:
  listen_ipv4: 0.0.0.0              # 监听所有 IPv4 网卡（默认仅 127.0.0.1）
  listen_ipv6: '-'                  # 关闭 IPv6 监听，避免双栈端口冲突（见常见问题 Q1）
  public_url: http://10.89.62.10:3000   # 改成你的服务器对外地址，邮件/链接会用到

security:
  password_salt: Kx9mP2vQ7wLnB4sR8tYhZ3cF6dJ0aE5g   # 密码哈希 pepper，务必改成你自己的随机串

改动核对：

grep -nE 'listen_ipv4|listen_ipv6|password_salt|public_url|^env' /opt/wakapi/config.yml

实测回显：

1:env: production
7:  listen_ipv4: 0.0.0.0              # set to '-' to disable ipv4
8:  listen_ipv6: '-'                  # set to '-' to disable ipv6
17:  public_url: http://10.89.62.10:3000   # required for links (e.g. password reset) in e-mail
87:  password_salt: Kx9mP2vQ7wLnB4sR8tYhZ3cF6dJ0aE5g                        # change this

⚠️ 注意：password_salt 是密码哈希的 pepper，首次启动前设定后不要再改，否则存量用户密码全部失效。示例值仅用于演示，生产请用 openssl rand -hex 24 生成自己的。

4.6 创建运行用户

useradd -r -s /usr/sbin/nologin -d /opt/wakapi wakapi
id wakapi
chown -R wakapi:wakapi /opt/wakapi

实测回显：

uid=999(wakapi) gid=999(wakapi) groups=999(wakapi)

4.7 systemd 托管

创建服务单元（注意：每行命令只操作一个单元）：

cat > /etc/systemd/system/wakapi.service <<'EOF'
[Unit]
Description=Wakapi - Coding time tracking backend (WakaTime-compatible)
After=network.target

[Service]
Type=simple
User=wakapi
Group=wakapi
WorkingDirectory=/opt/wakapi
ExecStart=/opt/wakapi/wakapi -config /opt/wakapi/config.yml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload
systemctl enable wakapi
systemctl start wakapi
systemctl is-active wakapi

enable 实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/wakapi.service → /etc/systemd/system/wakapi.service.

启动成功后 is-active 输出 active。若输出 activating 并反复重启，直接看「常见问题 Q1」（双栈端口冲突是默认配置下最常见的首个坑）。

4.8 验证服务

健康检查：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:3000/api/health
curl -s http://127.0.0.1:3000/api/health

实测回显：

HTTP 200
app=1
db=1

app=1 db=1 表示应用与数据库均健康。查看启动日志：

journalctl -u wakapi --no-pager -n 4 | tail -4

实测回显（节选）：

Oct 25 01:38:03 wakapi-srv wakapi[3008]: 2026-10-25 01:38:03.598 INFO scheduling summary aggregation
Oct 25 01:38:03 wakapi-srv wakapi[3008]: 2026-10-25 01:38:03.599 INFO 👉 Listening for HTTP... ✅ address="0.0.0.0:3000"

4.9 注册首个管理员账号并取 API Key

Wakapi 没有 CLI 建用户命令，首个账号通过 Web 注册接口创建（浏览器访问 http://<服务器>:3000 注册，或直接用 curl 提交注册表单）：

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:3000/signup \
  -d 'username=admin&email=admin%40example.org&password=q1w2e3r4&password_repeat=q1w2e3r4'

实测回显：302（注册成功并跳转）。

登录并进入设置页查看 API Key（Web 界面 Settings 页直接展示；也可 curl 登录后抓取）：

curl -s -c /tmp/ck.txt -X POST http://127.0.0.1:3000/login \
  -d 'username=admin&password=q1w2e3r4' -o /dev/null -w '%{http_code}\n'
curl -s -b /tmp/ck.txt http://127.0.0.1:3000/settings | grep -oE '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' | sort -u | head -1

实测回显：

302
51eb5817-e0e9-44ef-9644-43999eb962b3

这串 UUID 就是 admin 的 API Key。客户端接入时写入 ~/.wakatime.cfg：

[settings]
api_url = http://10.89.62.10:3000/api
api_key = 51eb5817-e0e9-44ef-9644-43999eb962b3

五、方案 B：Go 源码编译安装

适用于需要审计源码、打补丁或官方未提供对应架构的场景。

5.1 安装 Go 工具链与 Git

apt-get install -y git
curl -fsSL -o /root/go.tgz https://go.dev/dl/go1.25.3.linux-amd64.tar.gz
tar -C /usr/local -xzf /root/go.tgz
export PATH=/usr/local/go/bin:$PATH
go version

实测回显：

go version go1.25.3 linux/amd64

5.2 编译安装 Wakapi

注意 Wakapi 的 Git 标签不带 v 前缀，go install 必须写 @2.18.2 而不是 @v2.18.2（后者会报 invalid version: unknown revision）：

export GOPATH=/root/gopath
go install github.com/muety/wakapi@2.18.2
ls -la /root/gopath/bin/
/root/gopath/bin/wakapi --version

实测回显（节选，依赖下载输出省略）：

real	0m59.053s
total 53196
-rwxr-xr-x 1 root root 54463037 Oct 25 01:46 wakapi
dev

⚠️ 网络说明：实测 proxy.golang.org 默认走直连会连接超时/被拒；本次编译通过设置 https_proxy 走网络代理完成（也可配置国内 Go 模块镜像 GOPROXY=https://goproxy.cn,direct）。依赖下载与编译全程约 59 秒。

⚠️ go install 构建的二进制 --version 输出为 dev：版本号是官方 CI 在构建时通过 ldflags 注入的，自行编译不带该注入。如需注入，克隆源码后 go build -ldflags "-X github.com/muety/wakapi/config.Version=2.18.2"。

编译产物的后续配置、systemd 托管与方案 A 完全相同（把 /opt/wakapi/wakapi 替换为编译出的二进制即可），不再重复。

六、方案对比与选择建议

维度	方案 A：官方二进制	方案 B：源码编译
版本	2.18.2（`--version` 正常显示）	2.18.2（`--version` 显示 dev）
依赖	仅 curl/unzip	Go 1.25+ 工具链 + Git
网络	GitHub Releases 直连可用	Go 模块代理需镜像/代理
耗时	≈1 分钟	≈5 分钟（含工具链）
适用	生产/常规部署	审计、二次开发、冷门架构

选择建议：生产环境一律选方案 A；需要改代码或官方无对应架构预编译包时选方案 B。

七、配置说明

Wakapi 的全部行为由 /opt/wakapi/config.yml（或同名环境变量）控制。与安装直接相关的关键项：

配置项	默认值	本次改动	说明
`server.listen_ipv4`	`127.0.0.1`	`0.0.0.0`	对外提供服务的必改项
`server.listen_ipv6`	`::1`	`'-'`	双栈环境下与 IPv4 通配监听冲突，建议关闭（见 Q1）
`server.port`	`3000`	未改	可用 `WAKAPI_PORT` 环境变量覆盖
`db.dialect`	`sqlite3`	未改	SQLite 零依赖；生产可换 MySQL/Postgres（见配置详解篇）
`db.name`	`wakapi_db.db`	未改	SQLite 下为文件路径（相对 WorkingDirectory）
`security.password_salt`	空	已设随机串	密码哈希 pepper，首启前设定、之后勿改
`security.allow_signup`	`true`	未改	团队用可注册完账号后改 `false` 关闭公开注册

数据文件位置：SQLite 库文件 /opt/wakapi/wakapi_db.db，备份只需在停服后复制该文件（Wakapi 也内置每周数据清理与每月 vacuum 定时任务）。

八、常见问题

Q1：启动后一直 activating，日志报 listen tcp 0.0.0.0:3000: bind: address already in use？

这是 Wakapi 在「IPv4 通配 + IPv6 同端口」双栈监听下的已知问题（上游 issue #860）。默认配置 listen_ipv6: ::1 与 listen_ipv4: 0.0.0.0 同开时，部分内核把 IPv4 通配绑定映射到双栈，导致随后 IPv6 绑定撞车。实测日志：

INFO 👉 Listening for HTTP... ✅ address="0.0.0.0:3000"
INFO 👉 Listening for HTTP... ✅ address="[::1]:3000"
ERROR listen tcp 0.0.0.0:3000: bind: address already in use - possibly a dual-stack problem (https://github.com/muety/wakapi/issues/860)?

解决方案：在 config.yml 中把 listen_ipv6 改为 '-' 关闭 IPv6 监听（需要 IPv6 时反过来关闭 IPv4 通配、绑定具体地址）。改完 systemctl restart wakapi 即可。

Q2：把 listen_ipv6: - 写进配置后启动报 failed to read config !BADKEY="yaml: line 8: block sequence entries are not allowed in this context"？

- 在 YAML 里是列表项记号，必须加引号写成 '-' 或 "-"。实测未加引号时服务直接启动失败；加引号后恢复正常。

Q3：升级到新版本要注意什么？

停服 → 备份 wakapi_db.db → 替换二进制 → 启动。Wakapi 启动时会自动执行数据库迁移（日志可见 potentially running migration 序列）。特别注意 2.18.2 会为 heartbeats 表新建 idx_user_project_time 索引，官方提示大数据量实例该迁移可能耗时数小时，可在升级前手工对数据库执行 create index idx_user_project_time on heartbeats (user_id, project, time); 预建索引。

Q4：忘记管理员密码？

Web 登录页提供密码重置（需配置 SMTP 才能收到邮件）；未配邮件时可直接操作 SQLite：sqlite3 /opt/wakapi/wakapi_db.db 后删除对应用户或用另一账号登录后台重置。日常建议保留一个备用账号。

Q5：能否换 MySQL/Postgres？

可以。db.dialect 支持 mysql、postgres、sqlite3，配套修改 db.host/port/user/password/name 即可；官方说明 MySQL 测试最充分，适合多人团队实例。逐项参数见《Wakapi 2.18.2 配置参数详解》。

九、卸载与清理

systemctl stop wakapi
systemctl disable wakapi
rm /etc/systemd/system/wakapi.service
systemctl daemon-reload
rm -rf /opt/wakapi
userdel wakapi
rm -f /root/wakapi_linux_amd64.zip /root/go.tgz

SQLite 数据随 /opt/wakapi 一并删除；如有价值请先备份 wakapi_db.db。

十、参考链接

Wakapi GitHub Releases（2.18.2，查询日期 2026-10-25）：https://github.com/muety/wakapi/releases
Wakapi 官方文档与托管实例：https://wakapi.dev/
双栈端口冲突 issue #860：https://github.com/muety/wakapi/issues/860
官方 systemd 单元样例：https://github.com/muety/wakapi/blob/master/etc/wakapi.service
WakaTime 客户端插件体系：https://wakatime.com/plugins