Wakapi 2.18.2 配置参数详解

Wakapi 2.18.2 全部配置项逐项详解：config.yml 与环境变量双通道、server/app/db/security/mail/sentry 各段默认值与改动影响、生产配置模板与常见排障。

WakapiWakapi时间追踪SQLite2026/10/25

Wakapi 2.18.2 配置参数详解

目标：逐项讲清 Wakapi 2.18.2 的配置体系（config.yml 各键、对应环境变量、默认值、改动影响），并给出可直接套用的生产配置模板。本文基于 Ubuntu 22.04 上运行的 Wakapi 2.18.2 实例实测，配置示例取自官方随包默认 config.yml 原文。

一、环境信息

  • 软件版本：Wakapi 2.18.2（GitHub Releases 实查）
  • 配置载体：/opt/wakapi/config.yml（YAML，随官方发行包附带）+ 环境变量
  • 运行形态：systemd 托管（二进制）/ Compose 编排形态
  • 默认数据库：SQLite（wakapi_db.db）
  • 默认监听：IPv4 127.0.0.1:3000 + IPv6 ::1:3000

二、前置条件

三、参数查看与修改方式

Wakapi 只有两个配置来源，优先级为：环境变量 > config.yml。

  1. config.yml：启动时通过 -config 指定路径（默认读工作目录下 config.yml）。发行包自带的默认文件即完整配置清单（含注释），建议复制后逐项改；
  2. 环境变量：每个 YAML 键对应一个 WAKAPI_* 环境变量（命名规律：去掉层级前缀 server./db. 等后转大写，如 server.port → WAKAPI_PORT、db.dialect → WAKAPI_DB_TYPE）。完整对照表见官方 README 的 Configuration options 章节。

环境变量覆盖实测：在 config.yml 中 port: 3000 不变的情况下：

WAKAPI_PORT=3100 /opt/wakapi/wakapi -config /opt/wakapi/config.yml &
curl -s http://127.0.0.1:3100/api/health

实测回显：

app=1
db=1

服务实际监听 3100，证明环境变量覆盖了配置文件值。

💡 技术拓展：「文件 + 环境变量」双通道配置是 12-Factor 应用的标准形态。同类做法对比——Nginx/Apache 用「主配置 include 片段」，Redis 用「文件 + CONFIG SET 运行时热改」，PostgreSQL 用「postgresql.conf + ALTER SYSTEM」。Wakapi 走 12-Factor 路线：文件适合审计与版本管理，环境变量适合编排平台与云环境注入；Wakapi 不支持运行时热改，改完必须重启进程。

四、参数总览

段作用域关键键
顶层运行环境与调试env、quick_start、skip_migrations、enable_pprof
server监听、超时、TLS、日志listen_ipv4/ipv6、port、tls_*、base_path、public_url
app业务行为与定时任务leaderboard_*、aggregation_time、import_*、data_retention_months、custom_languages
db数据库连接dialect、host/port/user/password/name、max_conn
security认证与安全password_salt、allow_signup、oidc、trusted_header_auth、限流
sentry错误追踪集成dsn、sample_rate*
subscriptionsStripe 付费托管（官方 wakapi.dev 用）enabled 等
mailSMTP 发信smtp.host/port/username/password

五、核心参数分类详解

以下按段逐项详解，默认值均取自 2.18.2 发行包 config.yml 原文。

5.1 顶层段

键默认值说明
envproductiondev 开调试行为；生产保持 production（发行包默认已是）
quick_startfalse跳过启动时的汇总等初始化任务，仅供开发调试，生产勿开
skip_migrationsfalse跳过数据库迁移，仅开发用
enable_pproffalse暴露 Go pprof 性能剖析端点，排查性能问题时临时开启

5.2 server 段（监听与 Web 服务）

键（环境变量）默认值说明
listen_ipv4（WAKAPI_LISTEN_IPV4）127.0.0.1IPv4 监听地址；对外服务改 0.0.0.0；设 '-' 关闭
listen_ipv6（WAKAPI_LISTEN_IPV6）::1IPv6 监听地址；双栈冲突时设 '-'（YAML 中必须带引号，否则报 block sequence entries are not allowed）
listen_socket（WAKAPI_LISTEN_SOCKET）空UNIX Socket 路径，与 TCP 监听可并存；设 '-' 关闭
listen_socket_mode0666UNIX Socket 权限位
port（WAKAPI_PORT）3000TCP 监听端口
base_path（WAKAPI_BASE_PATH）/反向代理子路径场景（如 /wakapi）
public_url（WAKAPI_PUBLIC_URL）http://localhost:3000对外完整地址，用于邮件/页面内链接，生产必改
timeout_sec（WAKAPI_TIMEOUT_SEC）30请求超时秒数
tls_cert_path / tls_key_path空直接提供 HTTPS 的证书/私钥；留空则为 HTTP（官方推荐前面挂 Caddy/Nginx 终结 TLS）
log_format（WAKAPI_LOG_FORMAT）texttext 或 json，接入日志平台时选 json

⚠️ 实测排障：listen_ipv4: 0.0.0.0 与 listen_ipv6: ::1 同开时，部分环境会因双栈映射报 bind: address already in use（上游 issue #860）。本文实测解法：关闭 IPv6（listen_ipv6: '-'）。

5.3 app 段（业务行为与定时任务）

键（环境变量）默认值说明
leaderboard_enabledtrue是否开启公开排行榜
leaderboard_scope7_days排行榜统计区间（14_days、6_months 等）
leaderboard_generation_time0 0 6 * * *,0 0 18 * * *排行榜重算时间（扩展 cron，含秒位），可逗号分隔多个
leaderboard_require_authfalse排行榜是否仅登录用户可见，团队实例建议 true
aggregation_time0 15 2 * * *每日汇总聚合批任务时间（凌晨 2:15）
report_time_weekly0 0 18 * * 5每周五 18 点群发周报邮件（需配 SMTP）
data_cleanup_time0 0 6 * * 0每周日 6 点执行过期数据清理
optimize_database_time0 0 8 1 * *每月 1 日 8 点执行数据库 vacuum（SQLite/Postgres）或表优化（MySQL）
inactive_days7多少天未登录视为不活跃（用于指标统计）
import_enabledtrue是否允许从 WakaTime/其他 Wakapi 实例导入数据
import_backoff_min5两次导入尝试间冷却分钟数
import_max_rate24成功导入后须间隔的小时数
import_batch_size50导入时每事务写入的心跳条数
import_hosts_whitelist[]允许导入的来源主机名白名单（支持通配，空=不限）
heartbeat_max_age4320h可接受的最大心跳年龄（180 天），超龄心跳被拒收
data_retention_months-1心跳数据保留月数，-1 永久；设正数后由 data_cleanup_time 定时清理
max_inactive_months12无数据的不活跃账号保留月数，到期删号（-1 不删）
warm_cachestrue启动时预热项目统计缓存
custom_languages内置映射表文件扩展名→语言名自定义映射（如 .vue → Vue）
avatar_url_template内部渲染头像 URL 模板，可换成 Gravatar/Dicebear
date_format / datetime_formatGo 时间格式串页面日期时间显示格式

5.4 db 段（数据库）

键（环境变量）默认值说明
dialect（WAKAPI_DB_TYPE）sqlite3sqlite3 / mysql / postgres
host / port空MySQL/Postgres 地址；SQLite 留空
socket空MySQL 专用 UNIX Socket（替代 host:port）
user / password空数据库凭据（SQLite 留空）
name（WAKAPI_DB_NAME）wakapi_db.db库名；SQLite 下为文件路径（相对进程工作目录，建议写绝对路径）
charsetutf8mb4MySQL 连接字符集
max_conn10最大并发连接数（README 环境变量表标注默认 2，以发行包 config.yml 的 10 为准）
sslfalsePostgres 专用 TLS 开关
compressfalseMySQL 专用传输压缩
automigrate_fail_silentlyfalse启动迁移失败是否忽略（生产勿开，掩盖问题）

💡 技术拓展：Wakapi 通过 GORM 支持四种库。官方选型建议：SQLite 零依赖适合个人/小团队；MySQL（≥8.0）「测试最充分」适合生产；MariaDB（≥11.4）为 MySQL 开源替代（注意 2.18.1 迁移在 MariaDB 上有已知问题与规避方案）；Postgres 亦可。

5.5 security 段（认证与安全）

键（环境变量）默认值说明
password_salt（WAKAPI_PASSWORD_SALT）空密码哈希 pepper，生产必填且首启后勿改（改则存量密码全废）
cookie_key空Base64 编码 ≥32 字节，派生会话密钥；留空则每次启动随机生成（重启后全员掉线）
insecure_cookiestrue允许 HTTP 携带 Cookie；生产上 HTTPS 后应设 false
cookie_max_age172800登录 Cookie 有效期秒数（2 天），0 = 会话级
allow_signuptrue开放注册；团队实例建议注册完管理员后关
invite_codestrue注册关闭后可用邀请码纳新
signup_captchafalse注册验证码（公网实例建议开）
disable_local_authfalse禁用账号密码登录，强制 OIDC（企业 SSO 场景）
disable_webauthntrue禁用 WebAuthn（安全密钥/生物识别），默认禁用
disable_frontpagefalse关闭落地页（个人实例可开）
expose_metricsfalse暴露 /api/metrics Prometheus 指标（实测默认 404，开启后返回指标文本）
trusted_header_authfalse反向代理可信头认证（SSO 网关注入 Remote-User），配置不当有冒名风险，代理必须剥离该头
trusted_header_auth_keyRemote-User可信头字段名
trusted_header_auth_allow_signupfalse可信头首次登录自动建号
trust_reverse_proxy_ips空信任的反向代理 IP/CIDR 列表（逗号分隔）
signup_max_rate5/1h注册限流：每小时 5 次（实测响应头含 X-Ratelimit-*）
login_max_rate10/1m登录限流：每分钟 10 次
password_reset_max_rate5/1h密码重置限流
oidc[]OIDC 提供商列表（name/client_id/client_secret/endpoint/scopes 等），企业 SSO 接 Keycloak/GitLab 等

5.6 mail 段（SMTP 发信）

mail.enabled 默认 false，开启后支持密码重置邮件与每周报告：

键默认值说明
enabledfalse总开关
providersmtp当前仅支持 smtp
senderWakapi <wakapi@example.org>发件人地址，必须改成有效地址
skip_verify_mx_recordfalse跳过收件域 MX 记录校验（内网邮箱可开）
smtp.host / smtp.port空SMTP 服务器地址与端口（465 为 SSL，587/25 为 STARTTLS）
smtp.username / smtp.password空认证凭据（Compose 下可用 WAKAPI_MAIL_SMTP_PASS_FILE secret）
smtp.tls空是否全程 TLS（465）；false = STARTTLS 或明文
smtp.skip_verify—是否容忍自签证书

5.7 sentry / subscriptions 段

  • sentry.dsn 留空即关闭；填 DSN 后 sample_rate（0.75）与 sample_rate_heartbeats（0.1）控制追踪采样率——心跳量大，务必保持低采样；
  • subscriptions 整段仅供「搭建成付费托管服务」（官方 wakapi.dev 的 Stripe 计费），自托管保持 enabled: false。

六、生产配置模板

适用场景：8 GB 内存、SSD、20 人以内团队、HTTPS 由前置 Nginx 终结、MySQL 后端。

env: production

server:
  listen_ipv4: 127.0.0.1          # 只对本机，由 Nginx 反代
  listen_ipv6: '-'
  port: 3000
  base_path: /
  public_url: https://wakapi.example.com
  timeout_sec: 30
  log_format: json                # 接入日志平台

app:
  leaderboard_enabled: true
  leaderboard_require_auth: true  # 排行榜仅登录可见
  data_retention_months: 24       # 心跳保留 2 年
  max_inactive_months: -1         # 不自动删账号

db:
  dialect: mysql
  host: 127.0.0.1
  port: 3306
  user: wakapi
  password: 改用强密码
  name: wakapi
  charset: utf8mb4
  max_conn: 10

security:
  password_salt: 用 openssl rand -hex 24 生成
  insecure_cookies: false         # 已上 HTTPS
  allow_signup: false             # 管理员注册完后关闭
  invite_codes: true              # 邀请码纳新
  signup_captcha: true
  trust_reverse_proxy_ips: 127.0.0.1

mail:
  enabled: true
  provider: smtp
  sender: Wakapi <wakapi@example.com>
  smtp:
    host: smtp.example.com
    port: 465
    username: wakapi@example.com
    password: 改用邮箱授权码
    tls: true

关键取舍：单机上 Wakapi 与 MySQL 同机部署时 listen_ipv4 收回 127.0.0.1 由 Nginx 独占 80/443；insecure_cookies: false 必须在 HTTPS 就绪后再开，否则 HTTP 下无法登录。

七、常见问题

Q1：改了 listen_ipv6: - 后启动报 failed to read config !BADKEY=...？

- 是 YAML 列表记号，必须写 '-'（带引号）。实测不带引号启动即失败，加引号恢复。

Q2：/api/metrics 返回 404？

默认 security.expose_metrics: false。改为 true 重启后实测返回 Prometheus 文本指标（可接 Grafana 看板）。

Q3：徽章接口 /api/badge/<user>/interval:today 返回 403？

用户隐私默认不公开编码活动。登录 Web → Settings 中开启对应维度的公开分享后徽章即可访问。

Q4：改配置后没生效？

Wakapi 不支持热加载，必须重启进程；且注意环境变量优先级高于 config.yml——若 systemd 单元或 Compose 里设了同名环境变量，改配置文件不生效。

Q5：升级版本时数据库迁移卡住？

2.18.2 会为 heartbeats 表新建 idx_user_project_time 索引，大表实测可能耗时数小时（官方 Release 注记）。可在升级前手工执行 create index idx_user_project_time on heartbeats (user_id, project, time); 预建，迁移会自动跳过。

八、参考链接