环境变量

trackica 在进程启动时读取环境变量。修改后通常需要重启对应的 API、Web 或守护进程。Docker Compose 的 docker compose restart 不会重新读取 .env，要用 up -d 重建容器才能生效。

本页只列面向部署者的配置；测试变量和内部任务变量不在这里展开。本页是分组参考；完整部署步骤见自托管快速上手。

生产环境最小配置

DATABASE_URL=postgres://user:password@postgres:5432/trackica?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://trackica.example.com
TRACKICA_APP_URL=https://trackica.example.com
TRACKICA_PUBLIC_URL=https://api.trackica.example.com

还需要选择一种邮件服务，否则验证码和邀请只会写入服务端日志。

API 与数据库

在 Kubernetes 中设置 shutdown hold 时，terminationGracePeriodSeconds 要大于 hold 与实际退出所需时间之和。

对外地址与浏览器访问

前端和 API 使用不同 host、且浏览器直接访问 API 域时，必须设置 COOKIE_DOMAIN，否则浏览器读不到 CSRF cookie——所有写请求返回 403 CSRF validation failed，而读请求一切正常。取值用能同时覆盖两个 host 的最窄父域（.agent.example.com 优于 .example.com）。它会把登录会话 cookie 扩散到该域下的所有 host，只有这些 host 都由同一可信主体运维时才可用。修改后需要在两个 host 上清除旧 cookie 并重新登录。若采用自托管快速上手的同源配方（浏览器只访问 app 域），保持为空即可。不要填写 IP 地址，浏览器会忽略带 IP Domain 的 cookie。

邮件与登录

Resend

SMTP

只要 SMTP_HOST 非空，SMTP 就会优先于 Resend。

Google OAuth

注册范围

白名单的准确判断顺序见登录与注册。

附件存储

没有设置 S3_BUCKET 时，trackica 使用本地磁盘。

S3 或兼容存储

内网 MinIO 等 endpoint 无法被浏览器直接访问时，使用 ATTACHMENT_DOWNLOAD_MODE=proxy。

本地磁盘

CloudFront

Redis 与限流

反向代理后的部署需要填写真实代理网段。不要直接信任所有来源，否则客户端可以伪造转发 IP。

认证限流需要配置 REDIS_URL；未配置时，启动日志会提示认证限流已关闭。邀请限流在没有 Redis 时仍使用进程内存，配置 Redis 后则在多个副本间共享额度。如果已配置的 Redis 临时不可用，认证限流仍选择放行，而邀请创建会返回可重试的 503，不会在失去防护时发送邮件。

外部集成

不配置 GITHUB_APP_ID 和私钥时，PR 仍会正常关联、镜像和触发合并转 done，但卡片上不显示 CI 与可合并状态，"从 GitHub 选择"仓库入口也会禁用。

配置步骤见 GitHub 集成、飞书 Bot、Slack Bot和 Telegram Bot。

服务端 LLM

这组配置用于服务端的辅助生成能力，例如对话标题；它不是智能体执行任务时使用的 AI 编程工具凭据。

TRACKICA_LLM_MAX_RETRIES 是重试策略的唯一配置源。不设置时使用默认的 2 次；设为 0 表示每次调用只发一个请求；设为 1–5 表示最多重试这么多次。它是上限而不是配额：只有可重试的失败才会消耗它，请求成功或调用方自身的超时都会让调用提前结束。其它取值（负数、非数字、大于 5）会让服务启动失败，而不是被静默纠正。上限是一个延迟预算：退避从 0.5s 开始翻倍，上限 8s，更大的预算会超出调用方自身的超时，把可重试的失败变成超时失败。重试覆盖连接失败以及 HTTP 408、409、429 和 5xx；其余 4xx 直接返回。服务启动时会以 llm retry policy 打印生效策略，其中不包含任何凭据。

有四个功能会使用这一层，并把以下数据发送到你配置的 endpoint：

• 对话标题自动生成 —— 发送新对话中用户的第一条消息，原文发送。附件不会包含在内。
• 后续提问建议（智能体回复下方的按钮）—— 发送对话末尾的内容：最多 6 条消息，其中被追问的那条回复上限 3000 字符，更早的每条上限 800 字符。
• 甘特图状态摘要 —— 发送用户选择的最多 100 个事项，包括标识、标题、描述（最多 2000 字符）、状态、优先级、日期和项目标题。
• 项目快照摘要 —— 发送结构化项目事实：状态、负责人、里程碑、任务、交付、代码仓库检查、进度、健康信号和风险标记。不包含事项描述、评论、附件或聊天内容。 API key 与 base URL 都为空时，这一层关闭，不会发出任何上游请求——上面的功能都不再发送内容。如果你的政策不允许这一层把数据发到部署之外，这就是受支持的配置方式：对话继续使用客户端标题，后续提问与 AI 甘特图摘要不再出现，项目快照保留事实回退内容。

守护进程配置

下面的变量在运行智能体的电脑上读取，不是在 API 容器中读取。

各 AI 编程工具可以使用 TRACKICA_<PROVIDER>_PATH 覆盖命令路径；支持模型覆盖的工具还可以使用 TRACKICA_<PROVIDER>_MODEL。QwenPaw 和 MiniMax Code 没有模型变量，因为 trackica 不会向它们传模型；MiniMax Code 的路径变量是 TRACKICA_MCODE_PATH。详见 AI 编程工具对比。DeepSeek Harness 支持 TRACKICA_DSH_PATH 和 TRACKICA_DSH_MODEL（取值为 dsh 模型目录中的模型 id，例如 deepseek-official/deepseek-chat）。ZeroClaw 支持 TRACKICA_ZEROCLAW_PATH，但没有模型变量；模型由 ZeroClaw 的智能体配置管理。全机默认参数 TRACKICA_<PROVIDER>_ARGS 目前支持 Claude Code、Codex、CodeBuddy、Qwen Code 和 QwenPaw 五款工具。对应变量是 TRACKICA_CLAUDE_ARGS、TRACKICA_CODEX_ARGS、TRACKICA_CODEBUDDY_ARGS、TRACKICA_QWEN_ARGS 和 TRACKICA_QWENPAW_ARGS。例如：

TRACKICA_CLAUDE_PATH=/opt/bin/claude
TRACKICA_CLAUDE_ARGS=--max-turns 40

优先级为命令行 flag → 环境变量 → ~/.trackica/config.json → 内置默认。watchdog 的行为见守护进程与运行时。

守护进程配置的持久化

守护进程侧的常用配置也可以写入 ~/.trackica/config.json，不必依赖 shell 环境变量；命名 profile 的配置文件在 ~/.trackica/profiles/<name>/config.json：

trackica config set poll_interval 10s
trackica config show

支持的键：

几条取值规则：

• duration 类键接受正的 Go duration（如 10s、2h），0s 和负值会被拒绝。唯一例外是 agent_timeout：0s 合法，表示明确关闭执行时限。
• 传空字符串清除已持久化的值，回到环境变量或内置默认，例如 trackica config set poll_interval ""。
• max_concurrent_tasks 要求非负整数。
• 相对的 workspaces_root 值在保存时会转换为绝对路径。

观测与统计

接下来

• 登录与注册 — 登录方式与注册限制。
• 故障排查 — 部署问题的症状排查。
• 守护进程与运行时 — 守护进程侧的对应配置。