Vikunja 2.7.1 配置参数详解

Vikunja 的全部运行行为由一份 YAML 配置文件（默认 config.yml）驱动，同时所有配置项都支持以环境变量覆盖。本文基于 v2.7.1 官方发行包内置的完整配置样例（config.yml.sample，共 556 行）逐项梳理各配置段的参数、默认值与生产建议，并实测验证配置加载优先级与修改生效流程。安装部署操作见本专栏《Ubuntu 22.04 安装 Vikunja 2.7.1 指南》与《Vikunja 2.7.1 Docker Compose 部署指南》。

一、配置体系概述

1.1 配置文件位置与查找顺序

Vikunja 按以下优先级查找配置文件，命中即止：

1. 命令行参数 --config 显式指定的文件（优先级最高）；
2. 环境变量 VIKUNJA_SERVICE_ROOTPATH 指向目录下的 config.yml；
3. 可执行文件同目录下的 config.yml；
4. /etc/vikunja/config.yml（Linux 系统级路径）。

不同安装方式的默认配置路径实测：

1.2 环境变量覆盖规则

所有配置项均可被环境变量覆盖，映射规则为：VIKUNJA_ 前缀 + 配置层级用下划线 _ 拼接 + 全大写。例如：

该规则已实测：Docker Compose 部署中未提供任何配置文件，仅通过 VIKUNJA_DATABASE_*、VIKUNJA_SERVICE_* 环境变量即完成 PostgreSQL 连接与服务参数配置，API 信息接口返回的 frontend_url 与环境变量设定值一致。

1.3 配置修改与生效流程

Vikunja 不支持配置热加载，修改 config.yml 后需重启服务。以 systemd 部署为例的实测流程：在配置末尾的 service 块追加 motd（Message of the Day，会通过 /info 接口下发给前端）：

service:
  secret: "olKhSppGHa0BPCAkfNWifuWzEld48C9p"
  publicurl: "http://192.168.146.131:3456/"
  motd: "S9 验收实例 - 配置修改已生效"

重启并验证：

systemctl restart vikunja
systemctl is-active vikunja
curl -s http://localhost:3456/api/v1/info

回显（解析后）：

active
motd: 'S9 验收实例 - 配置修改已生效' | version: v2.7.1

motd 出现在 /api/v1/info 响应中，证明配置修改已生效。

二、service 段：核心服务参数

service 段控制 Web 服务监听、会话安全与全局功能开关，是最重要的配置段。

最小生产配置示例：

service:
  secret: "请替换为至少32位随机字符串"
  publicurl: "https://vikunja.example.com/"
  interface: ":3456"
  timezone: "Asia/Shanghai"
  enableregistration: false

三、database 段：数据库连接

PostgreSQL 生产示例：

database:
  type: "postgres"
  host: "192.168.1.10"
  user: "vikunja"
  password: "q1w2e3r4"
  database: "vikunja"
  sslmode: "verify-full"
  sslrootcert: "/etc/vikunja/pgsql-ca.pem"
  maxopenconnections: 100

四、redis 段与 keyvalue 段

redis 段（默认禁用）用于缓存与会话类数据；keyvalue 段定义键值存储后端，被限流计数器、指标缓存等内部模块使用。

单机部署保持默认即可；多副本水平扩展时必须启用 Redis 并将 keyvalue.type 设为 redis，否则各副本的限流计数与缓存互不可见。

五、cors 段：跨域访问

前后端分离部署（前端与 API 不同域名/端口）时，须把前端来源加入 origins；使用官方内嵌前端保持默认即可。

六、mailer 段：邮件发送

配置后可用 CLI 的 vikunja testmail 验证投递（用法见本专栏 CLI 篇）。

七、log 段：日志

systemd 部署保持 stdout 输出、由 journald 采集即可；需要文件落盘时把 standard/http 改为 file 并配置 log.path。

八、ratelimit 段：访问限流

九、files 段：附件存储

十、migration 段：第三方数据迁移

Vikunja 内置从 Todoist、Trello、Microsoft Todo、Wekan、TickTick、CSV、Vikunja 导出文件等来源的迁移器。公共参数：

Todoist / Trello / Microsoft Todo 三个迁移器默认关闭，各自需要到对应平台注册 OAuth 应用获得 clientid/clientsecret（Trello 为 key），并把 redirecturl 配置为 <service.publicurl>/migrate/<迁移器名>。

十一、auth 段：认证体系

11.1 local（本地认证）

auth.local.enabled 默认 true，基于数据库账号密码登录注册，无需额外配置。

11.2 openid（OpenID Connect）

注意：用环境变量配置 providers 时，配置文件中须先声明 provider 键，否则 Vikunja 无法感知该 provider 存在。

11.3 ldap（目录服务认证）

十二、metrics 段：监控

十三、defaultsettings 段：新用户默认偏好

该段只影响新注册用户的初始设置，修改后不回溯老用户。

十四、webhooks 与 outgoingrequests 段：外发请求安全

多用户实例强烈建议配置出口代理并保持 allownonroutableips 为 false，防止用户通过 Webhook 探测内网。

十五、audit 段：审计日志（付费功能）

十六、autotls 段：自动 HTTPS

使用前提：publicurl 配置为带有效 TLD 的公网域名，建议 interface 改为 :443。已有 Nginx/Caddy 反代时无需此功能。

十七、plugins 段与 license 段

十八、sentry、avatar、backgrounds、legal 段速览

十九、生产配置基线建议

综合各段分析，面向公网的生产实例建议基线如下：

service:
  secret: "<32位以上随机串>"
  publicurl: "https://vikunja.example.com/"
  timezone: "Asia/Shanghai"
  enableregistration: false
  ipextractionmethod: "xff"
  trustedproxies: "10.0.0.0/8,172.16.0.0/12"

database:
  type: "postgres"
  host: "<数据库主机>"
  user: "vikunja"
  password: "<强口令>"
  database: "vikunja"
  sslmode: "verify-full"

mailer:
  enabled: true
  host: "<SMTP主机>"
  fromemail: "vikunja@example.com"

ratelimit:
  enabled: true

log:
  format: "structured"

metrics:
  enabled: true
  username: "metrics"
  password: "<独立口令>"

outgoingrequests:
  allownonroutableips: false

要点回顾：secret 必须固定、publicurl 必须与实际访问地址一致、注册开关按需关闭、数据库跨机必开 TLS、反代后正确配置 IP 提取方式。

二十、参考链接

• Vikunja 官方配置文档：https://vikunja.io/docs/config-options/
• v2.7.1 发行包内置 config.yml.sample（随 https://dl.vikunja.io/vikunja/v2.7.1/ 下载）
• Vikunja 反向代理文档：https://vikunja.io/docs/reverse-proxy/
• OpenID 配置文档：https://vikunja.io/docs/openid/