Task Keeper 3.112 Docker Compose 部署指南

目标：用 Docker Compose 一键拉起 Task Keeper（PiGa）v3.112 + MariaDB 10.3 双服务栈，完成数据库初始化、admin 用户创建、JVM 限堆与登录验证。已在 Docker Engine 29 + Compose v5.6 环境实测通过。

一、环境信息

Docker Engine：29.9.2
Docker Compose：v5.6.1（docker compose 插件形态）
应用镜像：nymanjens/piga:v3.112（2026-10-19 推送，607MB）
数据库镜像：mariadb:10.3（503MB，官方 compose 指定版本）
编排项目名：task-keeper-3.112-stack
对外端口：9000（HTTP）
演示账号：admin / q1w2e3r4

二、镜像选型说明

Task Keeper 官方在 Docker Hub 维护 nymanjens/piga 镜像，tag 与 GitHub Releases 一一对应。常用 tag 实查（Docker Hub，查询日期 2026-10-25）：

tag	推送日期	说明
`latest`	2026-10-19	始终指向最新版，当前 = v3.112
`v3.112`	2026-10-19	本篇采用，固定版本便于复现与回滚
`v3.111`	2026-10-03	上一个版本
`v3.109`	2026-09-28	更早版本

选型建议：生产部署固定到具体版本号（如 v3.112），不要用 latest——后者会随上游发版漂移，重启时可能拉到未经验证的新版。MariaDB 侧沿用官方 compose 指定的 10.3（与应用 MySQL Connector/J 5.1 驱动兼容性经过官方验证）。

三、前置条件

已安装 Docker Engine 与 Compose 插件，执行 docker compose version 能输出版本号：

docker compose version

实测输出：

Docker Compose version v5.6.1

9000 端口未被占用：ss -ltn | grep :9000 无输出。
服务器可拉取 Docker Hub 镜像；如遇网络不通需先配置 registry 代理（见「八、常见问题」8.3）。

四、部署步骤

4.1 准备项目目录与配置文件

mkdir -p /opt/task-keeper/conf
cd /opt/task-keeper

官方 compose 中应用密钥通过环境变量注入，admin 初始密码则写在镜像内的 application.conf 里（默认 changeme）。为了把初始密码统一为本文演示口令 q1w2e3r4，先准备一份自定义配置挂载进容器。创建 /opt/task-keeper/conf/application.conf：

# Note: Error logs can be found in /tmp/piga-logs

# Secret key
play.http.secret.key="changeme"
play.http.secret.key=${?APPLICATION_SECRET}

# The application languages
play.i18n.langs = ["en"]
akka.http.parsing.max-uri-length = 16k

# Session configuration
play.http.session.maxAge = 60d

# Database configuration
db.default.driver=com.mysql.jdbc.Driver
db.default.url="jdbc:mysql://localhost/piga?user=mysqluser&password=mysqlpassword"
db.default.url=${?DATABASE_URL}
db.default.slick.profile = "slick.jdbc.MySQLProfile$"

# Application-specific configuration
app.setup.defaultPassword = "q1w2e3r4"

这份配置与镜像内置默认一致，仅把 app.setup.defaultPassword 从 changeme 改为 q1w2e3r4；${?APPLICATION_SECRET}、${?DATABASE_URL} 是 HOCON 的环境变量覆盖语法，由 compose 的 environment: 注入。

4.2 编写 docker-compose.yml

创建 /opt/task-keeper/docker-compose.yml：

name: task-keeper-3.112-stack

services:
  db:
    image: mariadb:10.3
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: q1w2e3r4
      MYSQL_DATABASE: piga
    volumes:
      - db_data:/var/lib/mysql

  web:
    image: nymanjens/piga:v3.112
    depends_on:
      - db
    command: bin/server
    restart: always
    ports:
      - "9000:9000"
    environment:
      APPLICATION_SECRET: ${APPLICATION_SECRET}
      DATABASE_URL: jdbc:mysql://db:3306/piga?user=root&password=q1w2e3r4
      JAVA_OPTS: -Xms256m -Xmx512m
    volumes:
      - ./conf/application.conf:/app/conf/application.conf:ro

volumes:
  db_data: {}

关键点解读：

name: task-keeper-3.112-stack：显式指定项目名，生成的容器名为 task-keeper-3112-stack-web-1 等（Compose 会去除项目名中的点号），避免多项目混部时互相影响；
JAVA_OPTS: -Xms256m -Xmx512m：限制 JVM 堆在 256–512MB。sbt 启动脚本 bin/server 会读取该变量，防止默认堆吃掉宿主机内存；
./conf/application.conf:/app/conf/application.conf:ro：只读挂载自定义配置，使 app.setup.defaultPassword 生效；
db_data 命名卷：MariaDB 数据落盘，栈重建后数据保留。

4.3 生成应用密钥并启动

APPLICATION_SECRET 用于会话 Cookie 签名与 External API 鉴权，必须是足够长的随机串：

export APPLICATION_SECRET="$(head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 32)"
echo "$APPLICATION_SECRET"

实测输出示例（每次生成均不同）：

GufWv2YDhOyZXnTOqACiTRQbZwCXlGdK

启动双服务栈：

cd /opt/task-keeper
docker compose up -d

实测输出（首次含镜像拉取，节选关键行）：

 Image nymanjens/piga:v3.112 Pulling 
 Image mariadb:10.3 Pulling 
 Image mariadb:10.3 Pulled 
 Image nymanjens/piga:v3.112 Pulled 
 Network task-keeper-3112-stack_default Created 
 Volume "task-keeper-3112-stack_db_data" Created 
 Container task-keeper-3112-stack-db-1 Started 
 Container task-keeper-3112-stack-web-1 Started

确认两个服务都 Up：

docker compose ps

实测输出：

NAME                           IMAGE                   COMMAND                  SERVICE   STATUS         PORTS
task-keeper-3112-stack-db-1    mariadb:10.3            "docker-entrypoint.s…"   db        4 seconds ago   Up 3 seconds   3306/tcp
task-keeper-3112-stack-web-1   nymanjens/piga:v3.112   "/__cacert_entrypoin…"   web       4 seconds ago   Up 3 seconds   0.0.0.0:9000->9000/tcp

4.4 初始化数据库与 admin 用户

镜像首次启动时库是空的，必须用一次性命令完成建表与建管理员（这两步在容器内执行 bin/server 的维护标志，跑完即退出）：

docker compose run --rm web bin/server -DdropAndCreateNewDb

实测输出末尾：

  Dropping the database tables (if present) and creating new ones...
  Done. Exiting.

docker compose run --rm web bin/server -DcreateAdminUser

实测输出：

  Creating admin user...
      loginName: admin
      password: q1w2e3r4
  Done. Exiting.

⚠️ 注意：-DdropAndCreateNewDb 会清空重建全部表，仅限首次初始化使用；日常重启、升级镜像都不要再跑。

4.5 验证部署

健康检查接口返回 OK 即表示应用与数据库连接正常：

curl -s http://localhost:9000/externalapi/healthcheck/

实测输出：

OK

验证 JVM 限堆生效（环境变量已注入 web 进程）：

docker compose exec web env | grep JAVA_OPTS

实测输出：

JAVA_OPTS=-Xms256m -Xmx512m

验证 admin 登录（表单 POST 返回 303 跳转，会话校验返回 true）：

curl -s -c /tmp/tk.txt -X POST http://localhost:9000/login/ \
  -d "loginName=admin&password=q1w2e3r4" -o /dev/null -w "%{http_code}\n"
curl -s -b /tmp/tk.txt http://localhost:9000/loggedin/

实测输出 303 与 true。浏览器访问 http://<服务器IP>:9000/ 即可开始使用。

五、数据持久化说明

本栈需要持久化的只有 MariaDB 数据卷 db_data（容器内路径 /var/lib/mysql），存放全部 5 张应用表。应用本身无状态（日志写容器内 /tmp/piga-logs/，不持久化）。

备份方式：

docker compose exec db mysqldump -u root -pq1w2e3r4 piga > piga-backup-$(date +%F).sql

恢复：

cat piga-backup-2026-10-25.sql | docker compose exec -T db mysql -u root -pq1w2e3r4 piga

六、环境变量表

变量	作用域	必填	说明
`APPLICATION_SECRET`	web	是	Play 应用密钥，≥32 位随机串；同时作为 External API 的 `appSecret`
`DATABASE_URL`	web	是	JDBC 连接串，指向 db 服务
`JAVA_OPTS`	web	建议	JVM 参数，本文固定 `-Xms256m -Xmx512m`
`MYSQL_ROOT_PASSWORD`	db	是	MariaDB root 密码，须与 `DATABASE_URL` 中一致
`MYSQL_DATABASE`	db	是	自动创建的业务库名，官方约定 `piga`

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

应用完整参数（会话、URI 长度、日志等）见本专栏《Task Keeper 3.112 配置参数详解》。Compose 场景下改配置的两种方式：

环境变量覆盖：application.conf 中带 ${?XXX} 的键（play.http.secret.key、db.default.url）直接改 compose 的 environment:；
挂载整文件：其余键（如 app.setup.defaultPassword、play.http.session.maxAge）改 ./conf/application.conf 后 docker compose up -d --force-recreate web 生效。

八、等价 docker run

不使用 Compose 时，等价命令如下（先自建桥网络保证服务名解析）：

docker network create task-keeper-net

docker run -d --name task-keeper-db --network task-keeper-net --restart always \
  -e MYSQL_ROOT_PASSWORD=q1w2e3r4 -e MYSQL_DATABASE=piga \
  -v task-keeper-db-data:/var/lib/mysql mariadb:10.3

docker run -d --name task-keeper-web --network task-keeper-net --restart always \
  -p 9000:9000 \
  -e APPLICATION_SECRET=GufWv2YDhOyZXnTOqACiTRQbZwCXlGdK \
  -e "DATABASE_URL=jdbc:mysql://task-keeper-db:3306/piga?user=root&password=q1w2e3r4" \
  -e "JAVA_OPTS=-Xms256m -Xmx512m" \
  -v /opt/task-keeper/conf/application.conf:/app/conf/application.conf:ro \
  nymanjens/piga:v3.112 bin/server

注意纯 docker run 形态下数据库主机名要写 db 容器名 task-keeper-db。初始化命令相应变为 docker run --rm --network task-keeper-net -e ... nymanjens/piga:v3.112 bin/server -DdropAndCreateNewDb。

九、常用运维命令

# 查看服务状态
docker compose ps

# 跟踪应用日志（Ctrl+C 退出）
docker compose logs -f web

# 重启应用（改配置后）
docker compose restart web

# 停止并启动整个栈
docker compose stop
docker compose start

# 进入 MariaDB 交互客户端
docker compose exec db mysql -u root -pq1w2e3r4 piga

# 彻底删除栈与数据（⚠️ 含数据卷，不可恢复）
docker compose down -v

十、常见问题

10.1 web 反复重启、日志报数据库连接失败

首次 up -d 时 MariaDB 初始化需要几秒，web 会因连不上库而报错重启，restart: always 会自动恢复。待 4.4 初始化完成后观察 docker compose ps 是否稳定 Up；若持续失败，用 docker compose logs web | tail -30 查看具体错误（常见为 DATABASE_URL 密码与 MYSQL_ROOT_PASSWORD 不一致）。

10.2 执行初始化命令提示「no configuration file provided」

docker compose 子命令必须在 docker-compose.yml 所在目录执行，先 cd /opt/task-keeper 再运行，或加 -f /opt/task-keeper/docker-compose.yml。

10.3 拉取镜像超时

Docker Hub 直连不通时，为 Docker 守护进程配置代理：编辑 /etc/docker/daemon.json 加入 "proxies": {"http-proxy": "http://<代理地址>:7897", "https-proxy": "http://<代理地址>:7897"}，执行 systemctl reload docker（或重启 docker 服务）后重试。

10.4 升级到新版本

改 compose 中 nymanjens/piga 的 tag 为新版本号，docker compose pull web && docker compose up -d web 即可；表结构由应用自动演进，不要重跑 -DdropAndCreateNewDb。升级前先按第五节备份数据库。

十一、参考链接

官方 compose 模板：https://github.com/nymanjens/piga/blob/master/docker-compose.yml
镜像仓库：https://hub.docker.com/r/nymanjens/piga
裸机安装：本专栏《Ubuntu 22.04 安装 Task Keeper 3.112 指南》
参数详解：本专栏《Task Keeper 3.112 配置参数详解》
External API：本专栏《Task Keeper 3.112 API 使用详解》