Wakapi 2.18.2 Docker Compose 部署指南

目标：用 Docker Compose 一键拉起 Wakapi 2.18.2，数据落卷持久化，注册账号并验证 API 可用。本文已在 Docker（ghcr.io/muety/wakapi:2.18.2 镜像）实测通过，Web 端口映射为宿主机 8133。

一、环境信息

镜像：ghcr.io/muety/wakapi:2.18.2（官方发布于 GitHub Container Registry，实测拉取约 71.5 MB）
数据库：SQLite（内嵌，数据落在容器卷 /data/wakapi_db.db）；扩展形态支持 MySQL / MariaDB / Postgres
端口：容器内 3000 → 宿主机 8133（8133 为本文示例，可自定）
Compose 项目名：wakapi-2-18-2-stack
部署目录约定：/opt/wakapi-stack/（含 docker-compose.yml）

二、镜像选型说明

镜像	说明
`ghcr.io/muety/wakapi:2.18.2`	官方发布镜像，本文采用；2.17.2 起基于 distroless 构建，容器内以 nonroot 用户（UID 65532）运行
`ghcr.io/muety/wakapi:latest`	滚动最新版，不建议生产固定使用
Dockerfile 自构建	仓库根目录自带 Dockerfile，适合定制；本文不涉及

⚠️ 注意：官方镜像没有同步发布到 Docker Hub（docker pull muety/wakapi 实测查无此仓库），请务必使用 ghcr.io/muety/wakapi 全名。

⚠️ 从 2.17.2 起镜像改为 distroless + nonroot（UID 65532）。若把数据目录以本地目录（bind mount）方式挂载，需先 chown -R 65532:65532 <目录>；本文使用命名卷（named volume），由 Docker 自动初始化属主，无此问题。

三、前置条件

已安装 Docker 与 Docker Compose v2（docker compose version 可查到 2.x）；
宿主机 8133 端口未被占用：ss -ltn | grep :8133 无输出；
能访问 ghcr.io（拉取慢或失败时给 Docker 守护进程配置网络代理后重试）。

四、部署步骤

4.1 编写 compose 文件

mkdir -p /opt/wakapi-stack

/opt/wakapi-stack/docker-compose.yml 内容如下：

name: wakapi-2-18-2-stack

services:
  wakapi:
    image: ghcr.io/muety/wakapi:2.18.2
    container_name: wakapi-2.18.2-compose
    init: true
    restart: unless-stopped
    ports:
      - "8133:3000"
    environment:
      WAKAPI_PASSWORD_SALT: "Kx9mP2vQ7wLnB4sR8tYhZ3cF6dJ0aE5g"
      WAKAPI_LISTEN_IPV4: "0.0.0.0"
      WAKAPI_LISTEN_IPV6: "-"
      WAKAPI_PUBLIC_URL: "http://127.0.0.1:8133"
      WAKAPI_DB_TYPE: "sqlite3"
      WAKAPI_DB_NAME: "/data/wakapi_db.db"
    volumes:
      - wakapi-data:/data

volumes:
  wakapi-data:

配置块逐项说明：

name: wakapi-2-18-2-stack：显式指定 Compose 项目名，避免多栈目录同名时互相影响；
init: true：启用 tini 作为 PID 1，正确回收子进程（官方示例推荐）；
WAKAPI_PASSWORD_SALT：密码哈希 pepper，务必改成自己的随机串（openssl rand -hex 24），首启后勿再改；
WAKAPI_LISTEN_IPV4/IPv6：容器内监听 0.0.0.0，同时显式关闭 IPv6 规避双栈端口冲突（上游 issue #860）；
WAKAPI_DB_NAME：SQLite 库文件路径，落在卷挂载点 /data 下实现持久化；
WAKAPI_PUBLIC_URL：实例对外地址，用于邮件与页面内链接，生产改为你的域名。

4.2 启动栈

cd /opt/wakapi-stack
docker compose up -d
docker compose ps

实测回显：

 Volume wakapi-2-18-2-stack_wakapi-data Created 
 Container wakapi-2.18.2-compose Started 
NAME                    IMAGE                         COMMAND         SERVICE   STATUS                   PORTS
wakapi-2.18.2-compose   ghcr.io/muety/wakapi:2.18.2   "/app/wakapi"   wakapi    Up 8 seconds (healthy)   0.0.0.0:8133->3000/tcp, [::]:8133->3000/tcp

STATUS 列为 Up (healthy)：镜像自带健康检查通过。

4.3 验证服务

健康检查端点：

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

实测回显：

health HTTP 200
app=1
db=1

查看启动日志确认调度任务与监听就绪：

docker compose logs --tail 6 wakapi

实测回显（节选，已去 ANSI 颜色码）：

wakapi-2.18.2-compose  | INFO scheduling project stats cache pre-warming
wakapi-2.18.2-compose  | INFO scheduling database vacuuming or optimization
wakapi-2.18.2-compose  | INFO scheduling leaderboard generation
wakapi-2.18.2-compose  | INFO 👉 Listening for HTTP... ✅ address="0.0.0.0:3000"

4.4 注册首个账号

浏览器访问 http://<宿主机>:8133 注册，或 curl 提交表单：

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

实测回显：signup HTTP 302（注册成功）。登录 Web 界面 Settings 页即可看到 API Key，客户端 ~/.wakatime.cfg 指向 http://<宿主机>:8133/api 完成接入。

五、数据持久化说明

命名卷 wakapi-2-18-2-stack_wakapi-data 挂载到容器 /data，内含 wakapi_db.db（SQLite 全量数据）；
备份：docker compose stop wakapi 后 docker run --rm -v wakapi-2-18-2-stack_wakapi-data:/data -v $PWD:/backup alpine tar czf /backup/wakapi-data.tgz /data；
升级：改 image: 标签后 docker compose pull && docker compose up -d，启动时自动跑数据库迁移；2.18.2 会为 heartbeats 表新建索引，大数据量实例注意迁移耗时（官方说明可能达数小时）。

六、环境变量表（常用）

Wakapi 每个 YAML 配置键都有对应环境变量，以下为部署常用项（完整对照见《Wakapi 2.18.2 配置参数详解》）：

环境变量	默认值	说明
`WAKAPI_PORT`	`3000`	容器内监听端口
`WAKAPI_LISTEN_IPV4`	`127.0.0.1`	容器内需设 `0.0.0.0`
`WAKAPI_LISTEN_IPV6`	`::1`	双栈冲突时设 `-` 关闭
`WAKAPI_DB_TYPE`	`sqlite3`	数据库类型：sqlite3 / mysql / postgres
`WAKAPI_DB_NAME`	`wakapi_db.db`	库名或 SQLite 文件路径
`WAKAPI_DB_HOST` / `WAKAPI_DB_PORT`	空	外部数据库地址（MySQL/Postgres 时必填）
`WAKAPI_DB_USER` / `WAKAPI_DB_PASSWORD`	空	外部数据库凭据
`WAKAPI_PASSWORD_SALT`	空	密码哈希 pepper，生产必填
`WAKAPI_ALLOW_SIGNUP`	`true`	是否开放注册
`WAKAPI_PUBLIC_URL`	`http://localhost:3000`	对外地址
`WAKAPI_EXPOSE_METRICS`	`false`	暴露 Prometheus `/api/metrics`
`WAKAPI_DATA_RETENTION_MONTHS`	`-1`	心跳数据保留月数，-1 不限

七、配置参数说明与配置文件挂载

环境变量适合 12-Factor 场景；配置项很多时也可挂载完整 config.yml：

    volumes:
      - wakapi-data:/data
      - ./config.yml:/app/config.yml:ro
    command: ["-config", "/app/config.yml"]

注意容器内工作目录为 /app，默认读取 /app/config.yml；环境变量优先级高于配置文件（实测 WAKAPI_PORT 可覆盖配置文件端口）。

八、扩展：Postgres 后端形态

SQLite 适合个人与小团队；多人高频上报建议 Postgres 或 MySQL。官方仓库 compose.yml 给出的形态为 Postgres 17 + Docker Secrets，要点（来源：官方 compose.yml，查询日期 2026-10-25）：

services:
  wakapi:
    image: ghcr.io/muety/wakapi:2.18.2
    environment:
      WAKAPI_DB_TYPE: "postgres"
      WAKAPI_DB_NAME: "wakapi"
      WAKAPI_DB_USER: "wakapi"
      WAKAPI_DB_HOST: "db"
      WAKAPI_DB_PORT: "5432"
      WAKAPI_DB_PASSWORD_FILE: "/run/secrets/db_password"
    secrets:
      - db_password
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: "wakapi"
      POSTGRES_PASSWORD_FILE: "/run/secrets/db_password"
      POSTGRES_DB: "wakapi"
    volumes:
      - wakapi-db-data:/var/lib/postgresql/data
    secrets:
      - db_password
secrets:
  db_password:
    environment: WAKAPI_DB_PASSWORD

Wakapi 对 WAKAPI_PASSWORD_SALT、WAKAPI_DB_PASSWORD、WAKAPI_MAIL_SMTP_PASS 三个敏感项支持 Docker Secrets（*_FILE 形式），不想用 secrets 可直接设同名环境变量。

九、等价 docker run

不用 Compose 时的等价命令：

docker volume create wakapi-data
docker run -d \
  --init \
  --name wakapi-2.18.2-compose \
  --restart unless-stopped \
  -p 8133:3000 \
  -e WAKAPI_PASSWORD_SALT=Kx9mP2vQ7wLnB4sR8tYhZ3cF6dJ0aE5g \
  -e WAKAPI_LISTEN_IPV4=0.0.0.0 \
  -e WAKAPI_LISTEN_IPV6=- \
  -e WAKAPI_PUBLIC_URL=http://127.0.0.1:8133 \
  -e WAKAPI_DB_TYPE=sqlite3 \
  -e WAKAPI_DB_NAME=/data/wakapi_db.db \
  -v wakapi-data:/data \
  ghcr.io/muety/wakapi:2.18.2

十、常用运维命令

docker compose ps                 # 查看栈状态
docker compose logs -f wakapi     # 跟踪日志
docker compose restart wakapi     # 重启服务
docker compose pull               # 拉取新镜像
docker compose up -d              # 应用变更/升级
docker compose down               # 停止并移除栈（卷保留）
docker compose down -v            # 连数据卷一起删除（危险，先备份）

十一、常见问题

Q1：docker compose up 后 STATUS 一直 starting 或 unhealthy？

看 docker compose logs wakapi：最常见是 listen tcp 0.0.0.0:3000: bind: address already in use 双栈冲突——确认 WAKAPI_LISTEN_IPV6: "-" 已设置（注意 YAML 里 - 必须带引号，否则解析失败，日志会报 block sequence entries are not allowed）。

Q2：旧版本升级到 2.17.2+ 后启动报权限错误（EACCES）？

2.17.2 起容器内用户变为 nonroot（UID 65532）。若使用本地目录 bind mount 存放 SQLite，执行 docker run --rm -v <卷或目录>:/data alpine chown -R 65532:65532 /data 修复属主后再启动。

Q3：注册页面打不开 / 注册按钮报错？

确认 WAKAPI_ALLOW_SIGNUP 未设为 false；团队内部实例可在管理员注册完成后设 WAKAPI_ALLOW_SIGNUP=false 并用邀请码（WAKAPI_INVITE_CODES）纳新。

Q4：如何从 WakaTime 官方导入历史数据？

登录 Web 界面 → Settings → Data Import，粘贴 WakaTime API Key 即可后台导入；受 WAKAPI_IMPORT_BACKOFF_MIN（默认 5 分钟冷却）与 WAKAPI_IMPORT_MAX_RATE（默认 24 小时间隔）限制。

十二、参考链接

官方 compose.yml（查询日期 2026-10-25）：https://github.com/muety/wakapi/blob/master/compose.yml
官方镜像（GHCR）：https://github.com/muety/wakapi/pkgs/container/wakapi
Wakapi 仓库 README（环境变量全表）：https://github.com/muety/wakapi
2.17.2 nonroot 变更说明：https://github.com/muety/wakapi/releases
Docker Secrets 官方文档：https://docs.docker.com/compose/how-tos/use-secrets/