Ubuntu 22.04 安装 Task Keeper 3.112 指南

目标：在一台 Ubuntu 22.04 服务器上从零完成 Task Keeper（上游项目 PiGa）v3.112 的安装：OpenJDK 11 + MariaDB 10.6 基础环境 → 官方 release 包下载解压 → 数据库初始化 → systemd 托管 → 登录验证。已在 Ubuntu 22.04.5 LTS（x86_64）实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64）
Java 运行时：OpenJDK 11.0.32.1（Ubuntu 官方仓库 openjdk-11-jdk-headless）
数据库：MariaDB 10.6.23（Ubuntu 官方仓库 mariadb-server）
应用版本：Task Keeper v3.112（2026-10-19 发布，发布件 release-v3.112.tar.gz，85.5MB）
发布件 SHA256：f425aca8f88eded5851a8dc919c89006abf18e1426c7f67767c562f34a460d15
安装目录：/opt/task-keeper（符号链接，指向 /opt/task-keeper-3.112）
监听端口：9000（HTTP）
演示账号：admin / q1w2e3r4

⚠️ 网络说明：本次实测时 GitHub Releases 直连下载超时不可用，已按「官方源 → 国内源 → 代理」降级链改用 HTTP 代理完成下载（见 4.3）。官方源恢复情况以当时网络为准。

二、前置条件

开始安装前，确认满足以下条件：

一台干净的 Ubuntu 22.04 服务器，拥有 root 权限（下文命令均以 root 执行）。
服务器可访问外网（用于下载 release 包）；如为纯内网环境，可在有网机器下载后离线拷贝（见 4.3 末尾说明）。
9000 端口未被占用：

ss -ltn | grep :9000

无输出即表示端口空闲。

三、版本选型说明

Task Keeper 没有发行版仓库包（无 apt/ppa），官方提供三种安装路径：

方案	交付物	适用场景	本篇是否覆盖
官方 Release 二进制包	`release-v3.112.tar.gz`（编译好的 Play 应用）	裸机/虚拟机正式部署	✅ 方案 A（主）
官方镜像编排	`nymanjens/piga:v3.112` 镜像	已使用编排环境	见本专栏《Task Keeper 3.112 Docker Compose 部署指南》
源码编译	Git 仓库 + sbt	二次开发	❌（官方 CI 用 sbt 构建，日常部署无需）

版本号规则：Task Keeper 采用 v3.xxx 递增式版本号，无 LTS/滚动之分，生产部署建议固定到具体版本（本文用 v3.112），避免 latest 漂移。版本清单见 https://github.com/nymanjens/piga/releases。

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

本节是完整主线：基础环境 → 下载 → 解压 → 配置 → 初始化 → systemd 托管 → 验证。

4.1 安装 OpenJDK 11

Task Keeper 官方要求 JDK 11。先更新软件源索引并安装：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y openjdk-11-jdk-headless wget curl

验证 Java 版本：

java -version

实测输出：

openjdk version "11.0.32.1" 2026-08-18
OpenJDK Runtime Environment (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-1ubuntu1-22.04-Ubuntu, mixed mode, sharing)

4.2 安装并初始化 MariaDB

Task Keeper 服务端通过 JDBC 连接 MariaDB/MySQL 存储全部数据。安装 MariaDB 并设为开机自启：

DEBIAN_FRONTEND=noninteractive apt-get install -y mariadb-server
systemctl enable mariadb
systemctl start mariadb
systemctl is-active mariadb

最后一条命令实测输出 active，表示数据库已在运行。

为 root 设置密码并创建应用数据库 piga（库名是官方默认，建议保持不变）：

mysqladmin -u root password 'q1w2e3r4'
mysql -u root -pq1w2e3r4 -e "CREATE DATABASE piga CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; SHOW DATABASES;"

实测输出：

Database
information_schema
mysql
performance_schema
piga
sys

piga 库已建好。生产环境建议另建独立账号（如 piga@localhost）并授权 piga.*，本文演示统一使用 root / q1w2e3r4。

4.3 下载并解压 release 包

从 GitHub Releases 下载 v3.112 发布件（约 85.5MB）：

cd /opt
wget https://github.com/nymanjens/piga/releases/download/v3.112/release-v3.112.tar.gz

⚠️ 注意：若直连 GitHub 超时/失败（本次实测即如此），改用代理下载：wget -e use_proxy=yes -e https_proxy=http://192.168.1.62:7897 <上述URL>（代理地址替换为实际可用的）；纯内网环境则在有网机器下载后用 scp 拷入。

核对完整性后解压到版本化目录，并建立稳定路径符号链接（便于今后升级切换）：

sha256sum /opt/release-v3.112.tar.gz
# 实测输出：f425aca8f88eded5851a8dc919c89006abf18e1426c7f67767c562f34a460d15  /opt/release-v3.112.tar.gz

mkdir -p /opt/task-keeper-3.112
tar -xzf /opt/release-v3.112.tar.gz -C /opt/task-keeper-3.112
ln -sfn /opt/task-keeper-3.112 /opt/task-keeper
ls /opt/task-keeper/

实测目录结构：

bin
conf
lib

其中 bin/server 是启动脚本（sbt-native-packager 生成的 bash 包装器），conf/application.conf 是主配置文件，lib/ 是 92 个依赖 jar。

4.4 修改应用配置

Task Keeper 的全部运行配置集中在 /opt/task-keeper/conf/application.conf（Play Framework HOCON 格式）。打开文件，修改以下三项：

# 生成 32 位随机应用密钥（用于会话 Cookie 签名与 External API 鉴权）
head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 32

把生成的随机串、数据库连接、管理员初始密码写入配置。修改后的 /opt/task-keeper/conf/application.conf 关键内容如下（其余保持默认）：

# Secret key
play.http.secret.key="OQnYaBOXBc6lLC4IFudvdoG46XLm9f8I"

# Database configuration
db.default.driver=com.mysql.jdbc.Driver
db.default.url="jdbc:mysql://localhost/piga?user=root&password=q1w2e3r4"
db.default.slick.profile = "slick.jdbc.MySQLProfile$"

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

逐项说明：

play.http.secret.key：Play 框架应用密钥，必须改为随机值，泄露会导致会话伪造与 External API 被滥用；
db.default.url：JDBC 连接串，用户/密码与 4.2 创建的一致；
app.setup.defaultPassword：下一步创建 admin 用户时使用的初始密码，改为自己要用的密码（本文演示用 q1w2e3r4）。

💡 技术拓展：JDBC 后端不止 MariaDB 一种。该应用 classpath 内含 MySQL/MariaDB、H2、SQLite 三类驱动——

数据库 slick profile 适用场景
MariaDB / MySQL slick.jdbc.MySQLProfile$ 生产部署（官方推荐，本篇采用）
H2 slick.jdbc.H2Profile$ 嵌入式试用
SQLite slick.jdbc.SQLiteProfile$ 嵌入式试用

本文按官方推荐采用 MariaDB；试用场景可选 H2/SQLite 免去独立数据库。

数据库	slick profile	适用场景
MariaDB / MySQL	`slick.jdbc.MySQLProfile$`	生产部署（官方推荐，本篇采用）
H2	`slick.jdbc.H2Profile$`	嵌入式试用
SQLite	`slick.jdbc.SQLiteProfile$`	嵌入式试用

4.5 初始化数据库表与 admin 用户

首次启动前必须先用启动脚本附带的两个维护标志完成初始化（它们执行完即退出，不会常驻）：

cd /opt/task-keeper
bin/server -DdropAndCreateNewDb

实测输出（末尾节选）：

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

验证 5 张表已创建：

mysql -u root -pq1w2e3r4 piga -e "SHOW TABLES;"

实测输出：

Tables_in_piga
DOCUMENT_ENTITIES
DOCUMENT_PERMISSION_AND_PLACEMENTS
ENTITY_MODIFICATION_ENTITY
TASK_ENTITIES
USERS

创建 admin 用户（密码取 4.4 配置的 app.setup.defaultPassword）：

bin/server -DcreateAdminUser

实测输出：

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

⚠️ 注意：-DdropAndCreateNewDb 会清空重建全部表，仅在首次安装或确定要重置数据时执行；日常升级版本千万不要再跑。

4.6 配置 JVM 堆内存并创建 systemd 服务

Task Keeper 是 JVM 应用，默认堆由机器内存比例决定，生产环境应显式限制在 256–512MB。sbt 启动脚本读取 JAVA_OPTS 环境变量，因此把堆参数写进 systemd 单元：

cat > /etc/systemd/system/task-keeper.service <<'EOF'
[Unit]
Description=Task Keeper (PiGa) list editor server
After=network.target mariadb.service
Requires=mariadb.service

[Service]
Type=simple
WorkingDirectory=/opt/task-keeper
ExecStart=/opt/task-keeper/bin/server
Environment=JAVA_OPTS="-Xms256m -Xmx512m"
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable task-keeper
systemctl start task-keeper

首次启动需加载全部 jar，等待约 20 秒后验证：

systemctl is-active task-keeper

实测输出 active。再用 jps -lv 确认 JVM 参数真实生效：

jps -lv | grep -v Jps

实测输出：

4969 play.core.server.ProdServerStart -Xms256m -Xmx512m -Duser.dir=/opt/task-keeper-3.112

可以看到主类 play.core.server.ProdServerStart 携带了 -Xms256m -Xmx512m，限堆生效。

4.7 验证服务

服务监听 9000 端口。依次验证端口、健康检查接口与登录页：

ss -ltn | grep 9000
curl -s http://localhost:9000/externalapi/healthcheck/
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9000/login/

实测输出依次为：

LISTEN 0      100                *:9000             *:*
OK
200

最后用 curl 走一遍真实登录流程（表单 POST → 303 跳转 → 会话校验）：

curl -s -c /tmp/tk.txt -b /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/，用 admin / q1w2e3r4 登录即可进入列表编辑器；用户管理入口在 http://<服务器IP>:9000/app/useradministration。

五、方案对比与选择建议

维度	方案 A：Release 二进制包（本篇）	方案 B：Docker 镜像（Compose 篇）
交付物	release-v3.112.tar.gz	nymanjens/piga:v3.112 镜像
依赖	自装 JDK 11 + MariaDB	仅需 Docker 与 Compose
进程托管	systemd（可精细控制 JVM 参数）	restart 策略
数据库	与系统共用的 MariaDB	编排内独立 MariaDB 10.3
适用	正式部署、需纳入系统运维体系	快速体验、已有编排环境

选择建议：长期运行的正式环境选方案 A（资源可控、便于备份与监控）；只想快速体验或已有编排平台，选方案 B。

六、配置说明

主配置文件即 4.4 修改的 /opt/task-keeper/conf/application.conf，日常最常接触的就是该文件中的应用密钥、数据库连接串与初始密码三项；更全的参数逐项说明（会话、URI 长度、日志等）见本专栏《Task Keeper 3.112 配置参数详解》。

两个运维要点：

修改配置后需重启生效：systemctl restart task-keeper。
错误日志位置：运行期异常日志在 /tmp/piga-logs/ 目录（配置文件首行注释标明），配合 journalctl -u task-keeper 排查。

七、常见问题

7.1 启动后 9000 端口一直没有监听

先查服务状态与日志：

systemctl status task-keeper --no-pager | head -10
journalctl -u task-keeper --no-pager | tail -30

实测中常见的两类原因：一是数据库未启动或 JDBC 密码错误（日志含 Access denied for user），回到 4.2 核对；二是首次启动较慢，JVM 加载 92 个 jar 需 15–30 秒，稍等再查。

7.2 初始化时提示数据库连不上

bin/server -DdropAndCreateNewDb 报 Communications link failure 之类错误时，依次确认：systemctl is-active mariadb 为 active；mysql -u root -pq1w2e3r4 -e "SELECT 1" 能连通；application.conf 中 db.default.url 的密码与 MariaDB 实际密码一致。

7.3 忘记 admin 密码怎么办

admin 密码以哈希形式存在 USERS 表。最简恢复方式是停服后修改配置再重建：

systemctl stop task-keeper
sed -i 's/app.setup.defaultPassword = "q1w2e3r4"/app.setup.defaultPassword = "q1w2e3r4new"/' /opt/task-keeper/conf/application.conf
cd /opt/task-keeper
bin/server -DcreateAdminUser
systemctl start task-keeper

实测输出：

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

⚠️ 注意：若服务仍在运行，bin/server -DcreateAdminUser 会被 /opt/task-keeper/RUNNING_PID 阻止并报错 This application is already running，因此必须先 systemctl stop task-keeper。

7.4 想升级到新版本怎么做

下载新版 tar.gz 解压到 /opt/task-keeper-<新版本>，把旧目录的 conf/application.conf 拷入，将 /opt/task-keeper 符号链接指向新目录，systemctl restart task-keeper 即可。表结构由应用在启动时自动演进，不要再执行 -DdropAndCreateNewDb（会清空数据）。升级前建议先 mysqldump -u root -pq1w2e3r4 piga > piga-backup.sql 备份。

八、卸载与清理

按安装逆序清理：

systemctl stop task-keeper
systemctl disable task-keeper
rm -f /etc/systemd/system/task-keeper.service
systemctl daemon-reload
rm -rf /opt/task-keeper /opt/task-keeper-3.112 /opt/release-v3.112.tar.gz
mysql -u root -pq1w2e3r4 -e "DROP DATABASE piga;"

如需连 MariaDB/JDK 一并卸载（确认无其他应用依赖后）：

apt-get remove -y --purge mariadb-server openjdk-11-jdk-headless

九、参考链接

官方仓库与 README：https://github.com/nymanjens/piga
v3.112 发布页：https://github.com/nymanjens/piga/releases/tag/v3.112
编排部署：本专栏《Task Keeper 3.112 Docker Compose 部署指南》
参数详解：本专栏《Task Keeper 3.112 配置参数详解》
External API：本专栏《Task Keeper 3.112 API 使用详解》