• 简体中文

      • 环境变量参考

      API 和 Worker 都通过环境变量读取运行配置。使用 Docker Compose、Helm 或其他容器平台时，把这些值注入对应容器即可。

      第一次部署只需要处理“基本”项。平台正常运行后，再按实际需求调整“进阶”项，不必一开始逐个配置。

      API 配置项

      类型配置项默认值用途与修改时机
      基本APP_ENVproduction运行模式；只有本地开发时显式改为 development。
      基本SECRET_ENCRYPTION_KEY空加密密钥；生产环境必须设置稳定随机值。
      基本DATABASE_URLpostgres://devops:devops@postgres:5432/devops?sslmode=disablePostgreSQL 连接串；换数据库或账号时改。
      基本REDIS_ADDRredis://localhost:6379/0完整 Redis URI，格式为 redis://用户名:密码@域名:端口/数据库；TLS 连接使用 rediss://。不再拆分配置用户名、密码或 DB。
      基本PUBLIC_BASE_URLhttp://localhost:8088平台外部地址；有公网域名、HTTPS、反代时改。OIDC Redirect URI 会按 {PUBLIC_BASE_URL}/api/v1/auth/oidc/callback 生成。
      进阶API_ADDR:8080API 容器监听地址；自定义端口时改。
      进阶APP_CORS_ORIGINShttp://localhost:8088允许访问 API 的前端 Origin；前后端不同域时改。
      进阶TRUSTED_PROXY_CIDRS空允许提供真实客户端地址的反向代理 CIDR，多个值用逗号分隔。默认不信任任何代理；只有确认请求必经受控代理时才配置，避免伪造 X-Forwarded-For 绕过按 IP 限流。
      进阶LOG_LEVELinfo日志级别；本地排障时可临时改为 debug。
      进阶DB_MAX_OPEN_CONNS20当前 API 进程最多打开的 PostgreSQL 连接数；多副本部署时按总副本数一起控制，避免打满数据库。
      进阶DB_MAX_IDLE_CONNS5当前 API 进程保留的空闲 PostgreSQL 连接数；连接紧张时调小。
      进阶DB_CONN_MAX_LIFETIME30m单个数据库连接最长复用时间；负载均衡、连接代理或数据库滚动维护时可适当调短。
      进阶DB_CONN_MAX_IDLE_TIME5m空闲数据库连接保留时间；连接紧张时调短。
      进阶METRICS_ENABLEDfalse是否启用独立 Prometheus metrics listener；默认关闭。设为 true 后 API 会使用默认监听地址 :9090。
      进阶METRICS_ADDR:9090metrics 监听地址；只在需要调整 API metrics 端口或绑定地址时修改。
      进阶METRICS_PATH/metricsPrometheus 抓取路径；只注册在独立 metrics listener 上。
      进阶OTEL_EXPORTER_OTLP_ENDPOINT空OpenTelemetry Collector 的 OTLP HTTP 地址；留空关闭 Trace、OTLP Metrics 和 OTel Logs 导出。API、Worker 和 Agent 使用同一个地址。
      进阶OTEL_RESOURCE_ATTRIBUTES空附加环境、集群等资源属性；多个 key=value 使用逗号分隔。
      进阶OTEL_EXPORTER_OTLP_HEADERS空Collector 鉴权 Header；生产环境从 Secret 注入，不写入公开配置文件。

      启用 metrics 后，只有 API 会在独立端口暴露 Prometheus 兼容入口，包含 API HTTP、连接池和依赖健康指标。Worker 与 Agent 不开放独立 metrics 端口，其任务、队列、构建、发布、模型和工具指标通过 OTLP 汇入统一指标后端。Grafana dashboard JSON 位于 grafana/dashboards/，需要时直接导入 Grafana。

      配置 OTEL_EXPORTER_OTLP_ENDPOINT 后，API、Worker 和 Agent 会同时通过 OpenTelemetry 上报链路、指标和结构化日志。最小配置与本地验证方式见接入可观测平台。

      API 在监听 HTTP 端口前会分别对 Redis 和 PostgreSQL 执行一次真实连接检查。任一依赖不可达、认证失败或 PostgreSQL migration 失败时，进程都会直接退出，不会以部分可用状态启动。启动后的短暂连接中断由 go-redis 和 database/sql 的连接池恢复；容器平台应负责重启启动失败的进程。

      OIDC 身份源的 Redirect URI 由 PUBLIC_BASE_URL 生成，后台“身份源”表单会直接展示可复制地址。准入策略默认要求 OIDC 返回非空邮箱且 email_verified=true；如果接入的是可信内部身份源，但无法返回标准 email_verified，可以在准入策略里关闭“要求 OIDC 邮箱已验证”，平台仍会要求邮箱非空。

      前端未登录时会按浏览器首选语言顺序选择界面语言，目前支持 zh-CN 和 en-US。登录后以账号设置里的语言偏好为准，并写入本地缓存，方便下次打开时立即使用同一语言。

      访问入口的可用域名后缀、外层访问协议、外层访问端口和 Gateway API 默认值在“运行集群”里维护。不同集群可以配置不同的网关域名后缀、GatewayClass 和共享 Gateway；同一集群也可以配置多个域名后缀。部署配置绑定到哪个集群，创建访问入口时就只能从该集群的后缀里选择一个，默认域名、短前缀补全和控制台访问链接也按该选择生成。外层 CDN 或反向代理已经提供 HTTPS 时，可以把对应集群的外层访问协议改为 https；它只影响控制台展示和跳转链接，不会修改集群内部 listener，也不会触发证书申请。

      前端构建配置项

      类型配置项默认值用途与修改时机
      进阶VITE_DOCS_BASE_URLhttps://luna-devops.liteyuki.org文档站基础地址；账单页等帮助链接会基于它生成。文档站独立域名或路径变化时，在构建前设置。

      Worker 配置项

      类型配置项默认值用途与修改时机
      基本APP_ENVproduction运行模式；和 API 保持一致。
      基本SECRET_ENCRYPTION_KEY空解密平台密钥；必须和 API 一致。
      基本DATABASE_URLpostgres://devops:devops@postgres:5432/devops?sslmode=disablePostgreSQL 连接串；和 API 指向同库。
      基本REDIS_ADDRredis://localhost:6379/0完整 Redis URI；必须和 API 使用同一连接串。TLS 连接使用 rediss://。
      基本BUILD_EXECUTOR_IMAGEmoby/buildkit:v0.24.0-rootlessBuildKit 镜像；构建集群拉不到默认镜像时改。
      进阶LOG_LEVELinfo日志级别；本地排障时可临时改为 debug。
      进阶DB_MAX_OPEN_CONNS20当前 Worker 进程最多打开的 PostgreSQL 连接数；多副本部署时按总副本数一起控制，避免打满数据库。
      进阶DB_MAX_IDLE_CONNS5当前 Worker 进程保留的空闲 PostgreSQL 连接数；连接紧张时调小。
      进阶DB_CONN_MAX_LIFETIME30m单个数据库连接最长复用时间；负载均衡、连接代理或数据库滚动维护时可适当调短。
      进阶DB_CONN_MAX_IDLE_TIME5m空闲数据库连接保留时间；连接紧张时调短。
      进阶DEPLOY_ROLLOUT_TIMEOUT_SECONDS600发布等待超时；应用启动慢时调大。
      进阶CERT_MANAGER_CLUSTER_ISSUERletsencrypt-http01证书 Issuer 名称；集群名称不同时改。
      进阶BUILD_EGRESS_MODErestricted构建出站模式；默认仅允许 DNS、公网 HTTP(S) 和已配置的私有源。只有明确接受构建访问集群内任意服务的风险时，才改为 permissive。
      进阶BUILD_JOB_TIMEOUT_SECONDS1800构建超时兜底；部署配置未设置超时时使用。大型项目构建慢时调大。
      进阶BUILD_JOB_TTL_SECONDS3600构建 Pod 保留时间；想看更久日志时调大。
      进阶BUILD_CACHE_ENABLEDfalse构建缓存开关；需要加速重复构建时开启。
      进阶BUILD_CACHE_TAGbuildcache构建缓存 tag；需要隔离缓存时改。
      进阶BUILD_NPM_REGISTRY空npm 镜像源；需要内部源时设置。
      进阶BUILD_PRIVATE_EGRESS_CIDRS空restricted 模式下额外允许的内网 CIDR。
      进阶BUILD_PRIVATE_EGRESS_PORTS443restricted 模式下的内网白名单端口；非标镜像站常用 5000、8081。
      进阶BUILD_BLOCKED_EGRESS_CIDRS空restricted 模式下额外禁止的 CIDR。

      Worker 不再监听独立 metrics 端口。配置 OTEL_EXPORTER_OTLP_ENDPOINT 后，任务、重试、队列深度、队列延迟、构建/发布结果与耗时、运行副本和网关同步指标会随其他遥测数据上报。

      Worker 同样只在 Redis 与 PostgreSQL 的启动连接检查都成功后才开始消费任务；启动后的连接中断由 Asynq、go-redis 和 database/sql 自行恢复。