配置与监控

大约 3 分钟

配置与监控

1. 常用配置

以下为日常安装和维护常用的配置。按需要修改，未列出的参数保持安装包默认值。

场景	配置与默认值
严格分离危险审批	TIMECHO_APPROVAL_DANGER_APPROVER_ROLES=DB_ADMIN；默认 DB_ADMIN,ADMIN
调整审批等待	TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS=600
调整查询超时	TIMECHO_CLI_TIMEOUT_SECONDS=30
网关不支持流式	TIMECHO_LLM_STREAM=false；默认 true
慢模型需要更长超时	TIMECHO_LLM_REQUEST_TIMEOUT_SECONDS=120
模型地址防私网	TIMECHO_SECURITY_BLOCK_PRIVATE_MODEL_ENDPOINTS=false；模型网关不在内网时建议设为 true
默认每日预算	TIMECHO_BUDGET_DAILY_TOKENS_PER_USER=0（不限），用户单独设置优先
预算日界	TIMECHO_BUDGET_ZONE=Asia/Shanghai
审计保留	TIMECHO_AUDIT_RETENTION_DAYS=180，0 表示永久，不能少于 180 天
后端内存	BACKEND_MEM_LIMIT=2g
指标抓取	TIMECHO_SECURITY_METRICS_TOKEN，非空至少 32 字节
四眼审批	TIMECHO_APPROVAL_FOUR_EYES=off/write/all
写操作逐次审批	TIMECHO_APPROVAL_SESSION_AUTO_WRITE=false
回收站保留	TIMECHO_SESSIONS_TRASH_RETENTION_DAYS=30
自动摘要阈值	TIMECHO_AGENT_SUMMARY_TRIGGER_RATIO=0.8
预测服务	TIMECHO_AI_BASE_URL=https://ai.timecho.com、TIMECHO_AI_MAX_ROWS=2000
查询导出	TIMECHO_EXPORT_MAX_ROWS=100000、TIMECHO_EXPORT_MAX_BYTES=52428800（50 MB，填写字节数）
对话文档大小	TIMECHO_DOCUMENTS_MAX_BYTES=20971520（20 MB）
对话文档数量	TIMECHO_DOCUMENTS_MAX_PER_SESSION=20
扫描件识别	TIMECHO_DOCUMENTS_OCR_ENABLED=true、TIMECHO_DOCUMENTS_OCR_MAX_PAGES=20
外部工具总开关	TIMECHO_MCP_ENABLED=true
外部工具允许主机	TIMECHO_MCP_ALLOWED_HOSTS，多个主机以逗号分隔；默认空，表示不限
禁止外部工具私网地址	TIMECHO_MCP_BLOCK_PRIVATE=false；改为 true 会拒绝私网及回环服务
接口文档	TIMECHO_API_DOCS_ENABLED=false；开启后仅平台管理员可访问
登录 Cookie 安全设置	TIMECHO_SECURITY_COOKIE_SECURE=auto；纯 HTTP 下不设为 true

新增后端环境变量时，在 deploy/ 创建 docker-compose.override.yml，例如：

services:
  backend:
    environment:
      TIMECHO_APPROVAL_DANGER_APPROVER_ROLES: DB_ADMIN
      TIMECHO_AGENT_APPROVAL_TIMEOUT_SECONDS: "900"

加载配置：将 .env 的 COMPOSE_FILE 改为 docker-compose.prod.yml:docker-compose.override.yml，然后执行 config -q 和 up -d。

注意：只在 .env 新增一行，不保证变量会被传进后端；单纯 restart 也不会加载新的环境变量。

2. 启用指标监控

接入 Prometheus 时，按以下步骤配置：

指标端点及本机端口映射已有内部测试记录；下面的 Prometheus 抓取配置本身尚未实测，需在目标环境验证。

在受控 .env 中填写 TIMECHO_SECURITY_METRICS_TOKEN，至少 32 字节随机值，可使用 openssl rand -hex 24 生成。妥善保存，不作为用户登录密码使用。
将下面端口映射合并到 docker-compose.override.yml。已有 backend 配置时合并字段，不重复定义 services/backend：
```
services:
  backend:
    ports:
      - "127.0.0.1:8090:8090"
```
按常用配置设置 COMPOSE_FILE，执行 docker compose config -q，再 docker compose up -d。

将以下抓取配置合并到同一宿主上的 Prometheus 配置，替换令牌，并按其管理方式加载：

scrape_configs:
  - job_name: timecho-agent
    metrics_path: /actuator/prometheus
    authorization:
      credentials: <指标抓取令牌>
    static_configs:
      - targets: ["127.0.0.1:8090"]

令牌配置文件限制读取权限。Prometheus 在另一主机或容器时，127.0.0.1 指向它自身；可让 Prometheus 加入应用的内部网络，使用 backend:8090，不将后端端口开放公网。

成功的标志：Prometheus 目标正常，返回 JVM、CPU、HTTP 或连接池等指标。404 时检查令牌是否已配置、是否经前端访问；401 时检查是否使用正确的指标令牌。

在同一宿主验证数据库执行就绪：

curl -fsS http://127.0.0.1:8090/actuator/health/readiness

健康检查成功后，再验证一次真实模型查询。