Task Keeper 3.112 配置参数详解

Task Keeper 3.112 配置参数详解：application.conf 全部键值、HOCON 环境变量覆盖、生产配置模板与 JVM 限堆验证。

Task KeeperTask Keeper任务管理自托管2026/10/25

Task Keeper 3.112 配置参数详解

目标：逐项讲清 Task Keeper（PiGa）v3.112 的全部运行配置——主配置文件 application.conf 每个键的含义、默认值与修改方式，并给出经过实测的生产配置模板。基于 Ubuntu 22.04 + MariaDB 10.6 裸机部署形态实测整理，配置项在容器形态下同样适用（见文中环境变量覆盖说明）。

一、环境信息

  • 应用版本：Task Keeper v3.112（Play Framework 2.8.20 / Scala 2.12 / Slick 3.3）
  • 配置文件：/opt/task-keeper/conf/application.conf（HOCON 格式）
  • 参考环境：Ubuntu 22.04.5 LTS、OpenJDK 11.0.32.1、MariaDB 10.6.23
  • 演示账号：admin / q1w2e3r4

二、前置条件

本文所有示例假设已按本专栏《Ubuntu 22.04 安装 Task Keeper 3.112 指南》完成安装，服务由 systemd 托管（systemctl status task-keeper 可查）。容器部署形态下配置文件的修改方式不同，见 3.2。

三、参数查看与修改方式

3.1 裸机/systemd 形态：直接编辑文件

配置文件位于安装目录下 conf/application.conf。修改后重启生效：

vim /opt/task-keeper/conf/application.conf   # 或 sed 批量替换
systemctl restart task-keeper

验证配置是否被加载（应用启动日志会打印数据库连接信息）：

journalctl -u task-keeper --no-pager | grep -iE "secret|database|initialized" | tail -5

3.2 容器形态：环境变量覆盖 + 文件挂载

application.conf 中带 ${?XXX} 的键（play.http.secret.key、db.default.url）可通过环境变量覆盖；其余键需要把自定义文件挂载到容器内 /app/conf/application.conf（只读）。具体操作见《Task Keeper 3.112 Docker Compose 部署指南》第七节。

四、参数总览

v3.112 的 application.conf 默认内容（实测自 release 包）：

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

# Secret key
# ~~~~~
play.http.secret.key="changeme"

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

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

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

# Application-specific configuration
# ~~~~~
app.setup.defaultPassword = "changeme"

按功能分为四组：安全密钥、国际化与 HTTP、会话、数据库与应用专属。逐组详解如下。

五、核心参数分类详解

5.1 安全密钥组

参数默认值实测建议说明
play.http.secret.keychangeme32 位随机串Play 会话 Cookie 签名密钥，同时用作 External API 的 appSecret
app.setup.defaultPasswordchangeme自定义强密码仅用于 bin/server -DcreateAdminUser 首次创建 admin 时的初始密码

play.http.secret.key 是全系统唯一根密钥：既签发会话 Cookie，又作为 External API 的共享密钥（详见《Task Keeper 3.112 API 使用详解》）。生产环境必须改成随机值，生成方式：

head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 32

实测输出示例：

OQnYaBOXBc6lLC4IFudvdoG46XLm9f8I

app.setup.defaultPassword 只在初始化时读取一次，之后 admin 密码以哈希存库。实测：若 admin 已存在，再次执行 -DcreateAdminUser 会用当前配置里的密码重建账号（可用于密码重置，需先停服，见《Ubuntu 22.04 安装 Task Keeper 3.112 指南》7.3）。

5.2 国际化与 HTTP 组

参数默认值说明
play.i18n.langs["en"]界面语言列表，release 包内仅附带 messages（en）、messages.nl、messages.nl-months（荷兰语）。无官方中文语言包，改 ["nl"] 可切换荷兰语
akka.http.parsing.max-uri-length16kHTTP 请求 URI 最大长度。默认 8k，官方提到 16k 是为了容纳较长的 External API URL（如 inserttask 的 base64 内容）

实测当前值：

grep -E "i18n.langs|max-uri-length" /opt/task-keeper/conf/application.conf

输出：

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

max-uri-length 默认已 16k，一般无需再调；如果你的 External API 报 414 URI Too Long，可进一步提到 32k。

5.3 会话组

参数默认值说明
play.http.session.maxAge60d会话 Cookie 有效期（60 天）。浏览器关闭后会话仍有效，直到过期

改为更短会话（如 7 天）：

play.http.session.maxAge = 7d

修改后重启服务生效。所有已签发的 Cookie 会在到期后失效，用户需重新登录。

5.4 数据库组

参数默认值说明
db.default.drivercom.mysql.jdbc.DriverJDBC 驱动类。release 包 classpath 内含 MySQL Connector/J 5.1.36，兼容 MariaDB
db.default.urljdbc:mysql://localhost/piga?user=mysqluser&password=mysqlpasswordJDBC 连接串，含库名、账号、密码
db.default.slick.profileslick.jdbc.MySQLProfile$Slick 方言。MariaDB/MySQL 用 MySQLProfile；H2 用 H2Profile$、SQLite 用 SQLiteProfile$

MariaDB 实测连接串（对应 4.2 创建的库与账号）：

db.default.url="jdbc:mysql://localhost/piga?user=root&password=q1w2e3r4"

💡 技术拓展：JDBC 驱动选型。release 包 lib/ 目录内含三种数据库驱动——

数据库驱动 jarslick profile适用场景
MariaDB / MySQLmysql-connector-java-5.1.36.jarMySQLProfile$生产（官方推荐）
H2h2-1.4.195.jarH2Profile$嵌入式试用
SQLitesqlite-jdbc-3.8.11.2.jarSQLiteProfile$嵌入式试用

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

六、生产配置模板

以下模板适用于 2GB 内存、单机部署、生产使用 的场景，已通过 systemd 托管 + JVM 限堆实测：

/opt/task-keeper/conf/application.conf：

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

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

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

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

# 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"

配套 systemd 单元 /etc/systemd/system/task-keeper.service（含 JVM 限堆 256–512MB）：

[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

部署后验证 JVM 参数生效：

jps -lv | grep -v Jps

实测输出：

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

七、常见问题

7.1 修改配置后没生效

Task Keeper 只在启动时读取 application.conf，改完必须重启：

systemctl restart task-keeper
systemctl is-active task-keeper

实测输出 active。若仍未生效，检查配置文件的 HOCON 语法（常见错误：字符串忘了加双引号、= 两侧空格不一致不会报错但建议统一风格）。

7.2 容器形态下如何覆盖 app.setup.defaultPassword

该键没有 ${?XXX} 环境变量占位，必须挂载自定义 application.conf 文件到容器 /app/conf/application.conf（只读），详见《Task Keeper 3.112 Docker Compose 部署指南》4.1。

7.3 界面语言能改成中文吗

官方 release 包仅提供英语（默认）与荷兰语（messages.nl、messages.nl-months）语言文件，无中文语言包。如需中文界面，需自行翻译 conf/messages 系列文件并重启服务。

7.4 如何查看当前生效的连接池/线程数

Task Keeper 使用 Play 默认 HikariCP 配置（连接池默认 10 连接），未在 application.conf 中暴露，通常无需调整。若需修改可在 application.conf 追加 db.default.hikaricp.maximumPoolSize=20 等 HOCON 键，重启后生效。

八、参考链接