# yaml-language-server: $schema=https://schema.zeabur.app/template.json
apiVersion: zeabur.com/v1
kind: Template
metadata:
name: wakapi
spec:
description: "\U0001F4CA A minimalist, self-hosted WakaTime-compatible backend for coding statistics"
coverImage: https://raw.githubusercontent.com/muety/wakapi/refs/heads/master/static/assets/images/screenshot.webp
icon: https://raw.githubusercontent.com/muety/wakapi/refs/heads/master/static/assets/images/icon.svg
variables:
- key: PUBLIC_DOMAIN
type: DOMAIN
name: Domain
description: What is the domain you want for your wakapi instance?
tags:
- Coding
- Wakatime
- Tracking
readme: |-
A template to deploy [muety/wakapi](https://github.com/muety/wakapi), a minimalist, self-hosted WakaTime-compatible backend for coding statistics.
## Configuration
While deploying, you should at least set a domain for your wakapi instance.
## Runtime Configuration
You can specify configuration options either via a config file (edit `/app/config.yml` using config editor in service settings) or via environment variables (edit in variables). Here is an overview of useful options:
| YAML key / Env. variable | Default | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `env` /
`ENVIRONMENT` | `dev` | Whether to use development- or production settings |
| `app.leaderboard_enabled` /
`WAKAPI_LEADERBOARD_ENABLED` | `true` | Whether to enable the public leaderboard |
| `app.leaderboard_scope` /
`WAKAPI_LEADERBOARD_SCOPE` | `7_days` | Aggregation interval for public leaderboard (see [here](https://github.com/muety/wakapi/blob/7d156cd3edeb93af2997bd95f12933b0aabef0c9/config/config.go#L71) for allowed values) |
| `app.leaderboard_generation_time` /
`WAKAPI_LEADERBOARD_GENERATION_TIME` | `0 0 6 * * *,0 0 18 * * *` | One or multiple times of day at which to re-calculate the leaderboard |
| `app.leaderboard_require_auth` /
`WAKAPI_LEADERBOARD_REQUIRE_AUTH` | `false` | Restrict leaderboard access to logged in users only |
| `app.aggregation_time` /
`WAKAPI_AGGREGATION_TIME` | `0 15 2 * * *` | Time of day at which to periodically run summary generation for all users |
| `app.report_time_weekly` /
`WAKAPI_REPORT_TIME_WEEKLY` | `0 0 18 * * 5` | Week day and time at which to send e-mail reports |
| `app.data_cleanup_time` /
`WAKAPI_DATA_CLEANUP_TIME` | `0 0 6 * * 0` | When to perform data cleanup operations (see `app.data_retention_months`) |
| `app.optimize_database_time` /
`WAKAPI_OPTIMIZE_DATABASE_TIME` | `0 0 8 1 * *` | When to perform database vacuuming (SQLite, Postgres) or table optimization (MySQL) |
| `app.import_enabled` /
`WAKAPI_IMPORT_ENABLED` | `true` | Whether data imports from WakaTime or other Wakapi instances are permitted |
| `app.import_batch_size` /
`WAKAPI_IMPORT_BATCH_SIZE` | `50` | Size of batches of heartbeats to insert to the database during importing from external services |
| `app.import_backoff_min` /
`WAKAPI_IMPORT_BACKOFF_MIN` | `5` | "Cooldown" period in minutes before user may attempt another data import |
| `app.import_max_rate` /
`WAKAPI_IMPORT_MAX_RATE` | `24` | Minimum number of hours to wait after a successful data import before user may attempt another one |
| `app.inactive_days` /
`WAKAPI_INACTIVE_DAYS` | `7` | Number of days after which to consider a user inactive (only for metrics) |
| `app.heartbeat_max_age /`
`WAKAPI_HEARTBEAT_MAX_AGE` | `4320h` | Maximum acceptable age of a heartbeat (see [`ParseDuration`](https://pkg.go.dev/time#ParseDuration)) |
| `app.warm_caches /`
`WAKAPI_WARM_CACHES` | `true` | Whether to perform some initial cache warming upon startup |
| `app.custom_languages` | - | Map from file endings to language names |
| `app.avatar_url_template` /
`WAKAPI_AVATAR_URL_TEMPLATE` | (see [`config.default.yml`](https://github.com/muety/wakapi/blob/master/config.default.yml)) | URL template for external user avatar images (e.g. from [Dicebear](https://dicebear.com) or [Gravatar](https://gravatar.com)) |
| `app.date_format` /
`WAKAPI_DATE_FORMAT` | `Mon, 02 Jan 2006` | Go time format strings to format human-readable date (see [`Time.Format`](https://pkg.go.dev/time#Time.Format)) |
| `app.datetime_format` /
`WAKAPI_DATETIME_FORMAT` | `Mon, 02 Jan 2006 15:04` | Go time format strings to format human-readable datetime (see [`Time.Format`](https://pkg.go.dev/time#Time.Format)) |
| `app.support_contact` /
`WAKAPI_SUPPORT_CONTACT` | `hostmaster@wakapi.dev` | E-Mail address to display as a support contact on the page |
| `app.data_retention_months` /
`WAKAPI_DATA_RETENTION_MONTHS` | `-1` | Maximum retention period in months for user data (heartbeats) (-1 for unlimited) |
| `app.max_inactive_months` /
`WAKAPI_MAX_INACTIVE_MONTHS` | `12` | Maximum number of inactive months after which to delete user accounts without data (-1 for unlimited) |
| `server.timeout_sec` /
`WAKAPI_TIMEOUT_SEC` | `30` | Request timeout in seconds |
| `server.base_path` /
`WAKAPI_BASE_PATH` | `/` | Web base path (change when running behind a proxy under a sub-path) |
| `server.public_url` /
`WAKAPI_PUBLIC_URL` | `http://localhost:3000` | URL at which your Wakapi instance can be found publicly |
| `security.disable_local_auth` /
`WAKAPI_DISABLE_LOCAL_AUTH` | `false` | Disables login via local credentials (username and password) to enforce OIDC provider login |
| `security.disable_webauthn` /
`WAKAPI_DISABLE_WEBAUTHN` | `true` | Disables login via WebAuthn (security keys, biometrics, etc.) |
| `security.password_salt` /
`WAKAPI_PASSWORD_SALT` | - | Pepper to use for password hashing |
| `security.insecure_cookies` /
`WAKAPI_INSECURE_COOKIES` | `true` | Whether or not to allow cookies over HTTP. For production, it is **highly recommended** to serve Wakapi via HTTPS and set this to `false`. |
| `security.cookie_max_age` /
`WAKAPI_COOKIE_MAX_AGE` | `172800` | Lifetime of authentication cookies in seconds or `0` to use [Session](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#Define_the_lifetime_of_a_cookie) cookies |
| `security.allow_signup` /
`WAKAPI_ALLOW_SIGNUP` | `true` | Whether to enable local user registration |
| `security.oidc_allow_signup` /
`WAKAPI_OIDC_ALLOW_SIGNUP` | `true` | Whether to enable user registration via OIDC |
| `security.signup_captcha` /
`WAKAPI_SIGNUP_CAPTCHA` | `false` | Whether the registration form requires solving a CAPTCHA |
| `security.invite_codes` /
`WAKAPI_INVITE_CODES` | `true` | Whether to enable registration by invite codes. Primarily useful if registration is disabled (invite-only server). |
| `security.disable_frontpage` /
`WAKAPI_DISABLE_FRONTPAGE` | `false` | Whether to disable landing page (useful for personal instances) |
| `security.expose_metrics` /
`WAKAPI_EXPOSE_METRICS` | `false` | Whether to expose Prometheus metrics under `/api/metrics` |
| `security.trusted_header_auth` /
`WAKAPI_TRUSTED_HEADER_AUTH` | `false` | Whether to enable trusted header authentication for reverse proxies (see [#534](https://github.com/muety/wakapi/issues/534)). **Use with caution!** |
| `security.trusted_header_auth_key` /
`WAKAPI_TRUSTED_HEADER_AUTH_KEY` | `Remote-User` | Header field for trusted header authentication. **Caution:** proxy must be configured to strip this header from client requests! |
| `security.trusted_header_auth_allow_signup` /
`WAKAPI_TRUSTED_HEADER_AUTH_ALLOW_SIGNUP` | `false` | Whether to allow creation of new users based on upstream trusted header authentication (see [#808](https://github.com/muety/wakapi/issues/808)) |
| `security.trust_reverse_proxy_ips` /
`WAKAPI_TRUST_REVERSE_PROXY_IPS` | - | Comma-separated list of IPv4 or IPv6 addresses or CIDRs of reverse proxies to trust to handle authentication (e.g. `172.17.0.1`, `192.168.0.0/24`, `[::1]`). |
| `security.signup_max_rate` /
`WAKAPI_SIGNUP_MAX_RATE` | `5/1h` | Rate limiting config for signup endpoint in format `/`, where `unit` is one of `s`, `m` or `h`. |
| `security.login_max_rate` /
`WAKAPI_LOGIN_MAX_RATE` | `10/1m` | Rate limiting config for login endpoint in format `/`, where `unit` is one of `s`, `m` or `h`. |
| `security.password_reset_max_rate` /
`WAKAPI_PASSWORD_RESET_MAX_RATE` | `5/1h` | Rate limiting config for password reset endpoint in format `/`, where `unit` is one of `s`, `m` or `h`. |
| `security.oidc` | `[]` | List of OpenID Connect provider configurations (for details, see [wiki](https://github.com/muety/wakapi/wiki/OpenID-Connect-login-(SSO))) |
| `security.oidc[0].name` /
`WAKAPI_OIDC_PROVIDERS_0_NAME` | - | Name / identifier for the OpenID Connect provider (e.g. `gitlab`) |
| `security.oidc[0].display_name` /
`WAKAPI_OIDC_PROVIDERS_0_DISPLAY_NAME` | - | Optional "human-readable" display name for the provider presented to the user |
| `security.oidc[0].client_id` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_ID` | - | OAuth client name with this provider |
| `security.oidc[0].client_secret` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_SECRET` | - | OAuth client secret with this provider |
| `security.oidc[0].endpoint` /
`WAKAPI_OIDC_PROVIDERS_0_ENDPOINT` | - | OpenID Connect provider API entrypoint (for [discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)) |
| `security.oidc[0].username_claim` /
`WAKAPI_OIDC_PROVIDERS_0_USERNAME_CLAIM` | - | Optionally spcified custom OIDC ID token claim to read username from (by `preferred_username`, `nickname` and `sub` are checked) |
| `security.oidc[0].scopes` /
`WAKAPI_OIDC_PROVIDERS_0_SCOPES` | - | Additional OAuth scopes to request beyond `openid`, `profile` and `email` (to be used in custom username claim) |
| `mail.enabled` /
`WAKAPI_MAIL_ENABLED` | `false` | Whether to allow Wakapi to send e-mail (e.g. for password resets) |
| `mail.sender` /
`WAKAPI_MAIL_SENDER` | - | Default sender address for outgoing mails |
| `mail.skip_verify_mx_record` /
`WAKAPI_MAIL_SKIP_VERIFY_MX_RECORD` | `false` | Whether to skip validating MX DNS record for user email addresses |
| `mail.provider` /
`WAKAPI_MAIL_PROVIDER` | `smtp` | Implementation to use for sending mails (one of [`smtp`]) |
| `mail.smtp.host` /
`WAKAPI_MAIL_SMTP_HOST` | - | SMTP server address for sending mail (if using `smtp` mail provider) |
| `mail.smtp.port` /
`WAKAPI_MAIL_SMTP_PORT` | - | SMTP server port (usually 465) |
| `mail.smtp.username` /
`WAKAPI_MAIL_SMTP_USER` | - | SMTP server authentication username |
| `mail.smtp.password` /
`WAKAPI_MAIL_SMTP_PASS` | - | SMTP server authentication password |
| `mail.smtp.tls` /
`WAKAPI_MAIL_SMTP_TLS` | `false` | Whether the SMTP server requires TLS encryption (`false` for STARTTLS or no encryption) |
| `mail.smtp.skip_verify` /
`WAKAPI_MAIL_SMTP_SKIP_VERIFY` | `false` | Whether to allow invalid or self-signed certificates for TLS-encrypted SMTP |
| `sentry.dsn` /
`WAKAPI_SENTRY_DSN` | – | DSN for to integrate [Sentry](https://sentry.io) for error logging and tracing (leave empty to disable) |
| `sentry.environment` /
`WAKAPI_SENTRY_ENVIRONMENT` | (`env`) | Sentry [environment](https://docs.sentry.io/concepts/key-terms/environments/) tag (defaults to `env` / `ENV`) |
| `sentry.enable_tracing` /
`WAKAPI_SENTRY_TRACING` | `false` | Whether to enable Sentry request tracing |
| `sentry.sample_rate` /
`WAKAPI_SENTRY_SAMPLE_RATE` | `0.75` | Probability of tracing a request in Sentry |
| `sentry.sample_rate_heartbeats` /
`WAKAPI_SENTRY_SAMPLE_RATE_HEARTBEATS` | `0.1` | Probability of tracing a heartbeat request in Sentry |
refer to [Original README](https://github.com/muety/wakapi/blob/master/README.md#-configuration-options) for all configuration options.
# Setup on Wakatime client
Wakapi relies on the open-source [WakaTime](https://github.com/wakatime/wakatime-cli) client tools. In order to collect statistics for Wakapi, you need to set them up.
1. **Set up WakaTime** for your specific IDE or editor. Please refer to the respective [plugin guide](https://wakatime.com/plugins)
2. **Edit your local `~/.wakatime.cfg`** file as follows.
```ini
[settings]
# replace localhost:3000 with Your wakapi server domain
api_url = http://localhost:3000/api
# Your Wakapi API key (get it from the web interface after having created an account)
api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b
```
Optionally, you can set up a [client-side proxy](https://github.com/muety/wakapi/wiki/Advanced-Setup:-Client-side-proxy) in addition.
services:
- name: postgresql
icon: https://raw.githubusercontent.com/zeabur/service-icons/main/marketplace/postgresql.svg
template: PREBUILT_V2
spec:
id: postgresql
source:
image: postgres:17
command:
- docker-entrypoint.sh
- -c
- config_file=/etc/postgresql/postgresql.conf
ports:
- id: database
port: 5432
type: TCP
volumes:
- id: data
dir: /var/lib/postgresql/data
instructions:
- title: Connection String
content: postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${PORT_FORWARDED_HOSTNAME}:${DATABASE_PORT_FORWARDED_PORT}/${POSTGRES_DATABASE}
- title: PostgreSQL Connect Command
content: psql "postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${PORT_FORWARDED_HOSTNAME}:${DATABASE_PORT_FORWARDED_PORT}/${POSTGRES_DATABASE}"
- title: PostgreSQL username
content: ${POSTGRES_USERNAME}
- title: PostgresSQL password
content: ${POSTGRES_PASSWORD}
- title: PostgresSQL database
content: ${POSTGRES_DATABASE}
- title: PostgreSQL host
content: ${PORT_FORWARDED_HOSTNAME}
- title: PostgreSQL port
content: ${DATABASE_PORT_FORWARDED_PORT}
env:
PGDATA:
default: /var/lib/postgresql/data/pgdata
expose: false
POSTGRES_CONNECTION_STRING:
default: postgresql://${POSTGRES_USERNAME}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DATABASE}
expose: true
POSTGRES_DATABASE:
default: ${POSTGRES_DB}
expose: true
POSTGRES_DB:
default: zeabur
expose: false
POSTGRES_HOST:
default: ${CONTAINER_HOSTNAME}
expose: true
POSTGRES_PASSWORD:
default: ${PASSWORD}
expose: true
POSTGRES_PORT:
default: ${DATABASE_PORT}
expose: true
POSTGRES_URI:
default: ${POSTGRES_CONNECTION_STRING}
expose: true
POSTGRES_USER:
default: root
expose: false
POSTGRES_USERNAME:
default: ${POSTGRES_USER}
expose: true
configs:
- path: /etc/postgresql/postgresql.conf
template: |
# https://github.com/postgres/postgres/blob/master/src/backend/utils/misc/postgresql.conf.sample
listen_addresses = '*'
max_connections = 100
shared_buffers = 128MB
dynamic_shared_memory_type = posix
max_wal_size = 1GB
min_wal_size = 80MB
log_timezone = 'Etc/UTC'
datestyle = 'iso, mdy'
timezone = 'Etc/UTC'
lc_messages = 'en_US.utf8'
lc_monetary = 'en_US.utf8'
lc_numeric = 'en_US.utf8'
lc_time = 'en_US.utf8'
default_text_search_config = 'pg_catalog.english'
permission: null
envsubst: null
healthCheck:
type: TCP
port: database
portForwarding:
enabled: true
- name: wakapi
icon: https://raw.githubusercontent.com/muety/wakapi/refs/heads/master/static/assets/images/icon.svg
dependencies:
- postgresql
template: PREBUILT_V2
spec:
id: wakapi
source:
image: ghcr.io/muety/wakapi:latest
ports:
- id: web
port: 3000
type: HTTP
volumes:
- id: data
dir: /data
env:
ENVIRONMENT:
default: production
expose: true
WAKAPI_DB_HOST:
default: ${POSTGRES_HOST}
expose: false
WAKAPI_DB_NAME:
default: ${POSTGRES_DATABASE}
expose: false
WAKAPI_DB_PASSWORD:
default: ${POSTGRES_PASSWORD}
expose: false
WAKAPI_DB_PORT:
default: ${POSTGRES_PORT}
expose: false
WAKAPI_DB_TYPE:
default: postgres
expose: false
WAKAPI_DB_USER:
default: ${POSTGRES_USERNAME}
expose: false
WAKAPI_INSECURE_COOKIES:
default: "false"
expose: true
WAKAPI_PUBLIC_URL:
default: ${ZEABUR_WEB_URL}
expose: true
configs: []
healthCheck:
type: TCP
port: web
portForwarding:
enabled: false
domainKey: WAKAPI_PUBLIC_DOMAIN
localization:
zh-CN:
description: "\U0001F4CA 一个简洁、可自托管的代码时间统计服务，与 WakaTime 兼容"
variables:
- key: PUBLIC_DOMAIN
type: DOMAIN
name: 域名
description: 你想把 wakapi 部署到哪个域名？
readme: |-
部署 [muety/wakapi](https://github.com/muety/wakapi) 的模板，这是一个极简、自托管的 WakaTime 兼容后端，用于统计编程数据。
## 配置
在部署之前，你至少需要为你的 wakapi 实例设置一个域名。
## 运行时配置
你可以通过配置文件（使用服务设置中的“配置文件编辑器”编辑 `/app/config.yml`）或通过环境变量（在“变量”中编辑）来指定配置选项。以下是一些常用选项：
| YAML 键 / 环境变量 | 默认值 | 描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `env` /
`ENVIRONMENT` | `dev` | 是否使用开发或生产环境，开发环境会输出更多的日志 |
| `app.leaderboard_enabled` /
`WAKAPI_LEADERBOARD_ENABLED` | `true` | 是否启用公开排行榜 |
| `app.leaderboard_scope` /
`WAKAPI_LEADERBOARD_SCOPE` | `7_days` | 公开排行榜的收集周期（允许值见[此处](https://github.com/muety/wakapi/blob/7d156cd3edeb93af2997bd95f12933b0aabef0c9/config/config.go#L71)） |
| `app.leaderboard_generation_time` /
`WAKAPI_LEADERBOARD_GENERATION_TIME` | `0 0 6 * * *,0 0 18 * * *` | 重新计算排行榜的时间，以 cron 表达式表示 |
| `app.leaderboard_require_auth` /
`WAKAPI_LEADERBOARD_REQUIRE_AUTH` | `false` | 限制排行榜仅限登录用户访问 |
| `app.aggregation_time` /
`WAKAPI_AGGREGATION_TIME` | `0 15 2 * * *` | 每天定期为所有用户生成汇总的时间点 |
| `app.report_time_weekly` /
`WAKAPI_REPORT_TIME_WEEKLY` | `0 0 18 * * 5` | 发送邮件报告的时间 |
| `app.data_cleanup_time` /
`WAKAPI_DATA_CLEANUP_TIME` | `0 0 6 * * 0` | 执行数据清理操作的时间（见 `app.data_retention_months`） |
| `app.optimize_database_time` /
`WAKAPI_OPTIMIZE_DATABASE_TIME` | `0 0 8 1 * *` | 执行数据库清理（SQLite、Postgres）或表优化（MySQL）的时间 |
| `app.import_enabled` /
`WAKAPI_IMPORT_ENABLED` | `true` | 是否允许从 WakaTime 或其他 Wakapi 实例导入数据 |
| `app.import_batch_size` /
`WAKAPI_IMPORT_BATCH_SIZE` | `50` | 从外部服务导入时，每次插入数据库的心跳包批量大小 |
| `app.import_backoff_min` /
`WAKAPI_IMPORT_BACKOFF_MIN` | `5` | 用户尝试再次导入数据前需等待的“冷却”时间（分钟） |
| `app.import_max_rate` /
`WAKAPI_IMPORT_MAX_RATE` | `24` | 成功导入数据后，用户再次尝试导入前需等待的最少小时数 |
| `app.inactive_days` /
`WAKAPI_INACTIVE_DAYS` | `7` | 将用户视为非活跃的天数（仅用于指标） |
| `app.heartbeat_max_age /`
`WAKAPI_HEARTBEAT_MAX_AGE` | `4320h` | 心跳包与现在的时间的最大间隔（见 [`ParseDuration`](https://pkg.go.dev/time#ParseDuration)） |
| `app.warm_caches /`
`WAKAPI_WARM_CACHES` | `true` | 是否在启动时执行一些初始缓存预热 |
| `app.custom_languages` | - | 文件后缀到语言名称的映射 |
| `app.avatar_url_template` /
`WAKAPI_AVATAR_URL_TEMPLATE` | （见 [`config.default.yml`](https://github.com/muety/wakapi/blob/master/config.default.yml)） | 外部用户头像图片的 URL 模板（例如来自 [Dicebear](https://dicebear.com) 或 [Gravatar](https://gravatar.com)） |
| `app.date_format` /
`WAKAPI_DATE_FORMAT` | `Mon, 02 Jan 2006` | 用于格式化人类可读日期的 Go 时间格式字符串（见 [`Time.Format`](https://pkg.go.dev/time#Time.Format)） |
| `app.datetime_format` /
`WAKAPI_DATETIME_FORMAT` | `Mon, 02 Jan 2006 15:04` | 用于格式化人类可读日期时间的 Go 时间格式字符串（见 [`Time.Format`](https://pkg.go.dev/time#Time.Format)） |
| `app.support_contact` /
`WAKAPI_SUPPORT_CONTACT` | `hostmaster@wakapi.dev` | 页面上“支持联系人”的电子邮件地址 |
| `app.data_retention_months` /
`WAKAPI_DATA_RETENTION_MONTHS` | `-1` | 用户数据（心跳包）的最大保留月数（-1 表示无限制） |
| `app.max_inactive_months` /
`WAKAPI_MAX_INACTIVE_MONTHS` | `12` | 删除无数据用户账户前的最大非活跃月数（-1 表示无限制） |
| `server.timeout_sec` /
`WAKAPI_TIMEOUT_SEC` | `30` | 请求超时时间（秒） |
| `server.base_path` /
`WAKAPI_BASE_PATH` | `/` | Web 基础路径（当在代理后运行于子路径时更改） |
| `server.public_url` /
`WAKAPI_PUBLIC_URL` | `http://localhost:3000` | 你的 Wakapi 实例可公开访问的 URL |
| `security.disable_local_auth` /
`WAKAPI_DISABLE_LOCAL_AUTH` | `false` | 禁用本地凭据（用户名和密码）登录，强制使用 OIDC 提供者登录 |
| `security.disable_webauthn` /
`WAKAPI_DISABLE_WEBAUTHN` | `true` | 禁用通过 WebAuthn 登录（安全密钥、生物识别等） |
| `security.password_salt` /
`WAKAPI_PASSWORD_SALT` | - | 用于密码哈希的 salt |
| `security.insecure_cookies` /
`WAKAPI_INSECURE_COOKIES` | `true` | 是否允许通过 HTTP 传输 cookie。在生产环境中，**强烈建议**通过 HTTPS 提供 Wakapi 并将此项设为 `false`。 |
| `security.cookie_max_age` /
`WAKAPI_COOKIE_MAX_AGE` | `172800` | 认证 cookie 的生命周期（秒），或设为 `0` 使用 [会话 cookie](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Cookies#Define_the_lifetime_of_a_cookie) |
| `security.allow_signup` /
`WAKAPI_ALLOW_SIGNUP` | `true` | 是否启用用户注册 |
| `security.oidc_allow_signup` /
`WAKAPI_OIDC_ALLOW_SIGNUP` | `true` | 是否允许通过 OIDC 注册用户 |
| `security.signup_captcha` /
`WAKAPI_SIGNUP_CAPTCHA` | `false` | 注册表单是否需要验证码 |
| `security.invite_codes` /
`WAKAPI_INVITE_CODES` | `true` | 是否启用邀请码注册。主要用于注册被禁用的情况。 |
| `security.disable_frontpage` /
`WAKAPI_DISABLE_FRONTPAGE` | `false` | 是否禁用登录页（对于个人实例很有用） |
| `security.expose_metrics` /
`WAKAPI_EXPOSE_METRICS` | `false` | 是否在 `/api/metrics` 下暴露 Prometheus 指标 |
| `security.trusted_header_auth` /
`WAKAPI_TRUSTED_HEADER_AUTH` | `false` | 是否为反向代理启用受信任标头认证（参见 [#534](https://github.com/muety/wakapi/issues/534)）。**谨慎使用！** |
| `security.trusted_header_auth_key` /
`WAKAPI_TRUSTED_HEADER_AUTH_KEY` | `Remote-User` | 用于受信任标头认证的标头字段。**注意：** 必须配置代理以从客户端请求中剥离此标头！ |
| `security.trusted_header_auth_allow_signup` /
`WAKAPI_TRUSTED_HEADER_AUTH_ALLOW_SIGNUP` | `false` | 是否允许基于上游受信任标头认证创建新用户（参见 [#808](https://github.com/muety/wakapi/issues/808)） |
| `security.trust_reverse_proxy_ips` /
`WAKAPI_TRUST_REVERSE_PROXY_IPS` | - | 受信任处理认证的反向代理的 IPv4 或 IPv6 地址或 CIDR 列表（逗号分隔），例如 `172.17.0.1`、`192.168.0.0/24`、`[::1]`。 |
| `security.signup_max_rate` /
`WAKAPI_SIGNUP_MAX_RATE` | `5/1h` | 注册端点的速率限制配置，格式为 `/`，其中 `unit` 为 `s`、`m` 或 `h`。 |
| `security.login_max_rate` /
`WAKAPI_LOGIN_MAX_RATE` | `10/1m` | 登录端点的速率限制配置，格式为 `/`，其中 `unit` 为 `s`、`m` 或 `h`。 |
| `security.password_reset_max_rate` /
`WAKAPI_PASSWORD_RESET_MAX_RATE` | `5/1h` | 密码重置端点的速率限制配置，格式为 `/`，其中 `unit` 为 `s`、`m` 或 `h`。 |
| `security.oidc` | `[]` | OpenID Connect 提供者配置列表（详情见 [wiki](https://github.com/muety/wakapi/wiki/OpenID-Connect-login-(SSO))） |
| `security.oidc[0].name` /
`WAKAPI_OIDC_PROVIDERS_0_NAME` | - | OpenID Connect 提供者的名称/标识符（例如 `gitlab`） |
| `security.oidc[0].display_name` /
`WAKAPI_OIDC_PROVIDERS_0_DISPLAY_NAME` | - | 向用户显示的提供者名称（可选） |
| `security.oidc[0].client_id` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_ID` | - | 与此提供者对应的 OAuth 客户端名称 |
| `security.oidc[0].client_secret` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_SECRET` | - | 与此提供者对应的 OAuth 客户端密钥 |
| `security.oidc[0].endpoint` /
`WAKAPI_OIDC_PROVIDERS_0_ENDPOINT` | - | OpenID Connect 提供者 API 入口点（用于[发现](https://openid.net/specs/openid-connect-discovery-1_0.html)） |
| `security.oidc[0].username_claim` /
`WAKAPI_OIDC_PROVIDERS_0_USERNAME_CLAIM` | - | 可选的自定义 OIDC ID 令牌声明，用于从中读取用户名（默认会检查 `preferred_username`、`nickname` 和 `sub`） |
| `security.oidc[0].scopes` /
`WAKAPI_OIDC_PROVIDERS_0_SCOPES` | - | 除 `openid`、`profile` 和 `email` 之外请求的额外 OAuth 范围（用于自定义用户名声明） |
| `mail.enabled` /
`WAKAPI_MAIL_ENABLED` | `false` | 是否允许 Wakapi 发送电子邮件（用于密码重置） |
| `mail.sender` /
`WAKAPI_MAIL_SENDER` | - | 邮件的默认发件人地址 |
| `mail.skip_verify_mx_record` /
`WAKAPI_MAIL_SKIP_VERIFY_MX_RECORD` | `false` | 是否跳过验证用户电子邮件地址的 MX DNS 记录 |
| `mail.provider` /
`WAKAPI_MAIL_PROVIDER` | `smtp` | 用于发送邮件的实现（可选值：[`smtp`]） |
| `mail.smtp.host` /
`WAKAPI_MAIL_SMTP_HOST` | - | 发送邮件的 SMTP 服务器地址（如果使用 `smtp` 邮件提供者） |
| `mail.smtp.port` /
`WAKAPI_MAIL_SMTP_PORT` | - | SMTP 服务器端口（通常为 465） |
| `mail.smtp.username` /
`WAKAPI_MAIL_SMTP_USER` | - | SMTP 服务器认证用户名 |
| `mail.smtp.password` /
`WAKAPI_MAIL_SMTP_PASS` | - | SMTP 服务器认证密码 |
| `mail.smtp.tls` /
`WAKAPI_MAIL_SMTP_TLS` | `false` | SMTP 服务器是否需要 TLS 加密（`false` 表示使用 STARTTLS 或无加密） |
| `mail.smtp.skip_verify` /
`WAKAPI_MAIL_SMTP_SKIP_VERIFY` | `false` | 是否允许 TLS 加密的 SMTP 使用无效或自签名证书 |
| `sentry.dsn` /
`WAKAPI_SENTRY_DSN` | – | 用于集成 [Sentry](https://sentry.io) 的 DSN，用于错误日志记录和追踪（留空以禁用） |
| `sentry.environment` /
`WAKAPI_SENTRY_ENVIRONMENT` | (`env`) | Sentry [环境](https://docs.sentry.io/concepts/key-terms/environments/) 标签（默认值为 `env` / `ENV`） |
| `sentry.enable_tracing` /
`WAKAPI_SENTRY_TRACING` | `false` | 是否启用 Sentry 请求追踪 |
| `sentry.sample_rate` /
`WAKAPI_SENTRY_SAMPLE_RATE` | `0.75` | Sentry 中追踪请求的概率 |
| `sentry.sample_rate_heartbeats` /
`WAKAPI_SENTRY_SAMPLE_RATE_HEARTBEATS` | `0.1` | Sentry 中追踪心跳请求的概率 |
所有配置选项请参考[原始 README](https://github.com/muety/wakapi/blob/master/README.md#-configuration-options)。
# 在 Wakatime 客户端上设置
Wakapi 依赖于开源的 [WakaTime](https://github.com/wakatime/wakatime-cli) 客户端工具。要为 Wakapi 收集统计数据，你需要对其进行设置。
1. **为你的特定 IDE 或编辑器设置 WakaTime**。请参考相应的[插件指南](https://wakatime.com/plugins)
2. **如下编辑本地的 `~/.wakatime.cfg` 文件**。
```ini
[settings]
# 将 localhost:3000 替换为你的 wakapi 服务器域名
api_url = http://localhost:3000/api
# 你的 Wakapi API 密钥（创建账户后从 Web 界面获取）
api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b
```
此外，你还可以选择设置[客户端代理](https://github.com/muety/wakapi/wiki/Advanced-Setup:-Client-side-proxy)。
zh-TW:
description: "\U0001F4CA 一個簡潔、可自託管的編碼時間統計服務，與 WakaTime 相容"
variables:
- key: PUBLIC_DOMAIN
type: DOMAIN
name: 域名
description: 你想把 wakapi 部署到哪個域名？
readme: |-
部署 [muety/wakapi](https://github.com/muety/wakapi) 的模板，這是一個極簡、自託管的 WakaTime 相容後端，用於統計程式設計資料。
## 配置
在部署之前，你至少需要為你的 wakapi 設定一個域名。
## 執行時配置
你可以透過配置檔案（使用服務設定中的“配置檔案編輯器”編輯 `/app/config.yml`）或透過環境變數（在“變數”中編輯）來指定配置選項。以下是一些常用選項：
| YAML 鍵 / 環境變數 | 預設值 | 描述 |
| ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `env` /
`ENVIRONMENT` | `dev` | 是否使用開發或生產環境，開發環境會輸出更多的日誌 |
| `app.leaderboard_enabled` /
`WAKAPI_LEADERBOARD_ENABLED` | `true` | 是否啟用公開排行榜 |
| `app.leaderboard_scope` /
`WAKAPI_LEADERBOARD_SCOPE` | `7_days` | 公開排行榜的收集週期（允許值見[此處](https://github.com/muety/wakapi/blob/7d156cd3edeb93af2997bd95f12933b0aabef0c9/config/config.go#L71)） |
| `app.leaderboard_generation_time` /
`WAKAPI_LEADERBOARD_GENERATION_TIME` | `0 0 6 * * *,0 0 18 * * *` | 重新計算排行榜的時間，以 cron 表示式表示 |
| `app.leaderboard_require_auth` /
`WAKAPI_LEADERBOARD_REQUIRE_AUTH` | `false` | 限制排行榜僅限登入使用者訪問 |
| `app.aggregation_time` /
`WAKAPI_AGGREGATION_TIME` | `0 15 2 * * *` | 每天定期為所有使用者生成彙總的時間點 |
| `app.report_time_weekly` /
`WAKAPI_REPORT_TIME_WEEKLY` | `0 0 18 * * 5` | 傳送郵件報告的時間 |
| `app.data_cleanup_time` /
`WAKAPI_DATA_CLEANUP_TIME` | `0 0 6 * * 0` | 執行資料清理操作的時間（見 `app.data_retention_months`） |
| `app.optimize_database_time` /
`WAKAPI_OPTIMIZE_DATABASE_TIME` | `0 0 8 1 * *` | 執行資料庫清理（SQLite、Postgres）或表最佳化（MySQL）的時間 |
| `app.import_enabled` /
`WAKAPI_IMPORT_ENABLED` | `true` | 是否允許從 WakaTime 或其他 Wakapi 例項匯入資料 |
| `app.import_batch_size` /
`WAKAPI_IMPORT_BATCH_SIZE` | `50` | 從外部服務匯入時，每次插入資料庫的心跳包批次大小 |
| `app.import_backoff_min` /
`WAKAPI_IMPORT_BACKOFF_MIN` | `5` | 使用者嘗試再次匯入資料前需等待的“冷卻”時間（分鐘） |
| `app.import_max_rate` /
`WAKAPI_IMPORT_MAX_RATE` | `24` | 成功匯入資料後，使用者再次嘗試匯入前需等待的最少小時數 |
| `app.inactive_days` /
`WAKAPI_INACTIVE_DAYS` | `7` | 將使用者視為非活躍的天數（僅用於指標） |
| `app.heartbeat_max_age /`
`WAKAPI_HEARTBEAT_MAX_AGE` | `4320h` | 心跳包與現在的時間的最大間隔（見 [`ParseDuration`](https://pkg.go.dev/time#ParseDuration)） |
| `app.warm_caches /`
`WAKAPI_WARM_CACHES` | `true` | 是否在啟動時執行一些初始快取預熱 |
| `app.custom_languages` | - | 檔案字尾到語言名稱的對映 |
| `app.avatar_url_template` /
`WAKAPI_AVATAR_URL_TEMPLATE` | （見 [`config.default.yml`](https://github.com/muety/wakapi/blob/master/config.default.yml)） | 外部使用者頭像圖片的 URL 模板（例如來自 [Dicebear](https://dicebear.com) 或 [Gravatar](https://gravatar.com)） |
| `app.date_format` /
`WAKAPI_DATE_FORMAT` | `Mon, 02 Jan 2006` | 用於格式化人類可讀日期的 Go 時間格式字串（見 [`Time.Format`](https://pkg.go.dev/time#Time.Format)） |
| `app.datetime_format` /
`WAKAPI_DATETIME_FORMAT` | `Mon, 02 Jan 2006 15:04` | 用於格式化人類可讀日期時間的 Go 時間格式字串（見 [`Time.Format`](https://pkg.go.dev/time#Time.Format)） |
| `app.support_contact` /
`WAKAPI_SUPPORT_CONTACT` | `hostmaster@wakapi.dev` | 頁面上“支援聯絡人”的電子郵件地址 |
| `app.data_retention_months` /
`WAKAPI_DATA_RETENTION_MONTHS` | `-1` | 使用者資料（心跳包）的最大保留月數（-1 表示無限制） |
| `app.max_inactive_months` /
`WAKAPI_MAX_INACTIVE_MONTHS` | `12` | 刪除無資料使用者賬戶前的最大非活躍月數（-1 表示無限制） |
| `server.timeout_sec` /
`WAKAPI_TIMEOUT_SEC` | `30` | 請求超時時間（秒） |
| `server.base_path` /
`WAKAPI_BASE_PATH` | `/` | Web 基礎路徑（當在代理後運行於子路徑時更改） |
| `server.public_url` /
`WAKAPI_PUBLIC_URL` | `http://localhost:3000` | 你的 Wakapi 例項可公開訪問的 URL |
| `security.disable_local_auth` /
`WAKAPI_DISABLE_LOCAL_AUTH` | `false` | 停用本地憑據（使用者名稱和密碼）登入，強制使用 OIDC 提供者登入 |
| `security.disable_webauthn` /
`WAKAPI_DISABLE_WEBAUTHN` | `true` | 停用透過 WebAuthn 登入（安全金鑰、生物識別等） |
| `security.password_salt` /
`WAKAPI_PASSWORD_SALT` | - | 用於密碼雜湊的 salt |
| `security.insecure_cookies` /
`WAKAPI_INSECURE_COOKIES` | `true` | 是否允許透過 HTTP 傳輸 cookie。在生產環境中，**強烈建議**透過 HTTPS 提供 Wakapi 並將此項設為 `false`。 |
| `security.cookie_max_age` /
`WAKAPI_COOKIE_MAX_AGE` | `172800` | 認證 cookie 的生命週期（秒），或設為 `0` 使用 [會話 cookie](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Cookies#Define_the_lifetime_of_a_cookie) |
| `security.allow_signup` /
`WAKAPI_ALLOW_SIGNUP` | `true` | 是否啟用使用者註冊 |
| `security.oidc_allow_signup` /
`WAKAPI_OIDC_ALLOW_SIGNUP` | `true` | 是否允許透過 OIDC 註冊使用者 |
| `security.signup_captcha` /
`WAKAPI_SIGNUP_CAPTCHA` | `false` | 登錄檔單是否需要驗證碼 |
| `security.invite_codes` /
`WAKAPI_INVITE_CODES` | `true` | 是否啟用邀請碼註冊。主要用於註冊被停用的情況。 |
| `security.disable_frontpage` /
`WAKAPI_DISABLE_FRONTPAGE` | `false` | 是否停用登入頁（對於個人例項很有用） |
| `security.expose_metrics` /
`WAKAPI_EXPOSE_METRICS` | `false` | 是否在 `/api/metrics` 下暴露 Prometheus 指標 |
| `security.trusted_header_auth` /
`WAKAPI_TRUSTED_HEADER_AUTH` | `false` | 是否為反向代理啟用受信任標頭認證（參見 [#534](https://github.com/muety/wakapi/issues/534)）。**謹慎使用！** |
| `security.trusted_header_auth_key` /
`WAKAPI_TRUSTED_HEADER_AUTH_KEY` | `Remote-User` | 用於受信任標頭認證的標頭欄位。**注意：** 必須配置代理以從客戶端請求中剝離此標頭！ |
| `security.trusted_header_auth_allow_signup` /
`WAKAPI_TRUSTED_HEADER_AUTH_ALLOW_SIGNUP` | `false` | 是否允許基於上游受信任標頭認證建立新使用者（參見 [#808](https://github.com/muety/wakapi/issues/808)） |
| `security.trust_reverse_proxy_ips` /
`WAKAPI_TRUST_REVERSE_PROXY_IPS` | - | 受信任處理認證的反向代理的 IPv4 或 IPv6 地址或 CIDR 列表（逗號分隔），例如 `172.17.0.1`、`192.168.0.0/24`、`[::1]`。 |
| `security.signup_max_rate` /
`WAKAPI_SIGNUP_MAX_RATE` | `5/1h` | 註冊端點的速率限制配置，格式為 `/`，其中 `unit` 為 `s`、`m` 或 `h`。 |
| `security.login_max_rate` /
`WAKAPI_LOGIN_MAX_RATE` | `10/1m` | 登入端點的速率限制配置，格式為 `/`，其中 `unit` 為 `s`、`m` 或 `h`。 |
| `security.password_reset_max_rate` /
`WAKAPI_PASSWORD_RESET_MAX_RATE` | `5/1h` | 密碼重置端點的速率限制配置，格式為 `/`，其中 `unit` 為 `s`、`m` 或 `h`。 |
| `security.oidc` | `[]` | OpenID Connect 提供者配置列表（詳情見 [wiki](https://github.com/muety/wakapi/wiki/OpenID-Connect-login-(SSO))） |
| `security.oidc[0].name` /
`WAKAPI_OIDC_PROVIDERS_0_NAME` | - | OpenID Connect 提供者的名稱/識別符號（例如 `gitlab`） |
| `security.oidc[0].display_name` /
`WAKAPI_OIDC_PROVIDERS_0_DISPLAY_NAME` | - | 向用戶顯示的提供者名稱（可選） |
| `security.oidc[0].client_id` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_ID` | - | 與此提供者對應的 OAuth 客戶端名稱 |
| `security.oidc[0].client_secret` /
`WAKAPI_OIDC_PROVIDERS_0_CLIENT_SECRET` | - | 與此提供者對應的 OAuth 客戶端金鑰 |
| `security.oidc[0].endpoint` /
`WAKAPI_OIDC_PROVIDERS_0_ENDPOINT` | - | OpenID Connect 提供者 API 入口點（用於[發現](https://openid.net/specs/openid-connect-discovery-1_0.html)） |
| `security.oidc[0].username_claim` /
`WAKAPI_OIDC_PROVIDERS_0_USERNAME_CLAIM` | - | 可選的自定義 OIDC ID 令牌宣告，用於從中讀取使用者名稱（預設會檢查 `preferred_username`、`nickname` 和 `sub`） |
| `security.oidc[0].scopes` /
`WAKAPI_OIDC_PROVIDERS_0_SCOPES` | - | 除 `openid`、`profile` 和 `email` 之外請求的額外 OAuth 範圍（用於自定義使用者名稱宣告） |
| `mail.enabled` /
`WAKAPI_MAIL_ENABLED` | `false` | 是否允許 Wakapi 傳送電子郵件（用於密碼重置） |
| `mail.sender` /
`WAKAPI_MAIL_SENDER` | - | 郵件的預設發件人地址 |
| `mail.skip_verify_mx_record` /
`WAKAPI_MAIL_SKIP_VERIFY_MX_RECORD` | `false` | 是否跳過驗證使用者電子郵件地址的 MX DNS 記錄 |
| `mail.provider` /
`WAKAPI_MAIL_PROVIDER` | `smtp` | 用於傳送郵件的實現（可選值：[`smtp`]） |
| `mail.smtp.host` /
`WAKAPI_MAIL_SMTP_HOST` | - | 傳送郵件的 SMTP 伺服器地址（如果使用 `smtp` 郵件提供者） |
| `mail.smtp.port` /
`WAKAPI_MAIL_SMTP_PORT` | - | SMTP 伺服器埠（通常為 465） |
| `mail.smtp.username` /
`WAKAPI_MAIL_SMTP_USER` | - | SMTP 伺服器認證使用者名稱 |
| `mail.smtp.password` /
`WAKAPI_MAIL_SMTP_PASS` | - | SMTP 伺服器認證密碼 |
| `mail.smtp.tls` /
`WAKAPI_MAIL_SMTP_TLS` | `false` | SMTP 伺服器是否需要 TLS 加密（`false` 表示使用 STARTTLS 或無加密） |
| `mail.smtp.skip_verify` /
`WAKAPI_MAIL_SMTP_SKIP_VERIFY` | `false` | 是否允許 TLS 加密的 SMTP 使用無效或自簽名證書 |
| `sentry.dsn` /
`WAKAPI_SENTRY_DSN` | – | 用於整合 [Sentry](https://sentry.io) 的 DSN，用於錯誤日誌記錄和追蹤（留空以停用） |
| `sentry.environment` /
`WAKAPI_SENTRY_ENVIRONMENT` | (`env`) | Sentry [環境](https://docs.sentry.io/concepts/key-terms/environments/) 標籤（預設值為 `env` / `ENV`） |
| `sentry.enable_tracing` /
`WAKAPI_SENTRY_TRACING` | `false` | 是否啟用 Sentry 請求追蹤 |
| `sentry.sample_rate` /
`WAKAPI_SENTRY_SAMPLE_RATE` | `0.75` | Sentry 中追蹤請求的機率 |
| `sentry.sample_rate_heartbeats` /
`WAKAPI_SENTRY_SAMPLE_RATE_HEARTBEATS` | `0.1` | Sentry 中追蹤心跳請求的機率 |
所有配置選項請參考[原始 README](https://github.com/muety/wakapi/blob/master/README.md#-configuration-options)。
# 在 Wakatime 客戶端上設定
Wakapi 依賴於開源的 [WakaTime](https://github.com/wakatime/wakatime-cli) 客戶端工具。要為 Wakapi 收集統計資料，你需要對其進行設定。
1. **為你的特定 IDE 或編輯器設定 WakaTime**。請參考相應的[外掛指南](https://wakatime.com/plugins)
2. **如下編輯本地的 `~/.wakatime.cfg` 檔案**。
```ini
[settings]
# 將 localhost:3000 替換為你的 wakapi 伺服器域名
api_url = http://localhost:3000/api
# 你的 Wakapi API 金鑰（建立賬戶後從 Web 介面獲取）
api_key = 406fe41f-6d69-4183-a4cc-121e0c524c2b
```
此外，你還可以選擇設定[客戶端代理](https://github.com/muety/wakapi/wiki/Advanced-Setup:-Client-side-proxy)。