• 简体中文

      • Agent 配置

      源码联调默认先读取根目录 .env，luna-agent/.env.local 只用于 Agent 专属覆盖；Docker Compose 同样使用根目录 .env 作为唯一填写入口，并只向 Agent 注入日志、OpenTelemetry、Agent 数据库池和诊断开关等真实依赖。Compose 固定使用 NODE_ENV=production、AUTH_MODE=bff-hmac 和容器内部 API 地址。

      基础配置

      配置项名称默认值说明
      NODE_ENVdevelopment选择 Agent 运行模式；可填 development、test 或 production。
      HOST127.0.0.1设置 Agent 监听主机；填写 IP 或主机名。
      PORT8091设置 Agent 监听端口；填写 1–65535 的整数。
      LOG_FORMATauto选择终端日志渲染；可填 auto、console 或 json，生产容器应使用 json。
      LOG_COLORauto控制 console 日志颜色；可填 auto、always 或 never，NO_COLOR 会强制关闭。
      LOG_LEVELinfo设置日志级别；可填 debug、info、warn 或 error。
      DATABASE_URL空连接 PostgreSQL；填写 PostgreSQL 连接 URI。
      AUTH_MODEdevelopment选择内部请求鉴权模式；可填 development 或 bff-hmac。
      AI_INTERNAL_SECRET1空鉴权 API 与 Agent 的内部请求；填写至少 32 字节的密钥。
      LUNA_API_BASE_URL空设置 Agent 访问 API 的地址；填写 HTTP(S) URL。
      OTEL_EXPORTER_OTLP_ENDPOINT空设置遥测数据接收端；填写 Collector 的 OTLP/HTTP URL。
      1. 说明：生产环境必须使用 bff-hmac，并与 API 共享同一个 AI_INTERNAL_SECRET。

      生产模式必须同时提供 PostgreSQL 与 Luna API 配置。就绪探针会实时检查数据库 Schema 和 Provider 配置；任一依赖不可用时返回 503，Agent 不会继续接收新 Run。活动 Run 的增量事件只保留在当前 Agent 进程内，因此生产部署固定为单副本；进程重启会把未完成 Run 收敛为 interrupted，已经提交的 时间线与终态事实仍可从 PostgreSQL 回读。

      高级配置

      数据库连接

      配置项名称默认值说明
      AI_DATABASE_MAX_CONNECTIONS10限制 Agent 进程的 PostgreSQL 连接池；填写 1–100 的整数，并为 API 与 Worker 预留数据库连接预算。
      AI_DATABASE_CONNECTION_TIMEOUT_MS5000限制等待空闲 PostgreSQL 连接的时间；填写 100–30000 的整数，单位为毫秒。
      AI_DATABASE_STATEMENT_TIMEOUT_MS15000限制单条 Agent SQL 的执行时间；填写 1000–120000 的整数，单位为毫秒。

      可观测

      配置项名称默认值说明
      OTEL_RESOURCE_ATTRIBUTES空设置 OpenTelemetry 资源属性；填写逗号分隔的 key=value。
      OTEL_EXPORTER_OTLP_HEADERS空鉴权 Collector 请求；填写逗号分隔的 key=value Header。
      OTEL_SERVICE_VERSION空标记 Agent 的遥测版本；填写版本字符串。
      AI_OBSERVABILITY_CAPTURE_CONTENTfalse控制是否在受控 Trace 中按原文记录模型与工具内容；可填 true 或 false，工具目录声明的敏感路径仍会排除，单字段 UTF-8 JSON 超过 128 KiB 时整项省略，日志始终只保留元数据。
      AI_OBSERVABILITY_CAPTURE_DATABASE_SPANSfalse控制是否为每条 PostgreSQL 查询生成 Span；可填 true 或 false。

      上下文管理

      Agent 使用固定的上下文边界：用户单轮文本最多为 128 KiB，历史超过 32 轮时压缩较旧内容并保留最近 16 轮。工具结果、摘要请求和续跑消息同样使用平台内置上限。这些限制用于保护请求传输和进程内存，不代表 Token 数，也不需要部署管理员调参。

      Agent 每轮只注入当前任务需要的工作流参考，不把参考重复写入历史；“继续”一类纯延续输入会根据最近一次明确目标重新选择参考。用户和页面信息以及已完成交互按固定边界重放。摘要更新会开启新的缓存前缀周期，首次请求出现一次冷启动属于预期行为，后续轮次会复用该摘要前缀。

      Docker Compose

      Compose 不向 Agent 注入 PUBLIC_BASE_URL、Redis、平台加密密钥、首个管理员或 Worker 执行策略。API 与 Agent 共享的 AI_INTERNAL_SECRET 只需在根 .env 填写一次。

      配置项名称默认值说明
      DEVOPS_IMAGE_TAGnightly选择 Docker Compose 使用的 Agent 镜像版本；填写镜像标签。