• 简体中文

    • 环境变量

    Data Agent 在不同部署模式下都依赖一组核心环境变量来描述项目名称和元数据库（PostgreSQL）。建议在部署前梳理清楚这些变量的值，并通过 Docker Compose 或集群 Secret 的方式统一管理。

    核心变量清单

    变量说明默认/示例
    PROJECT当前实例的唯一标识，参与多项目隔离与日志区分。建议使用品牌英文名，不要包含空格和特殊字符
    DB_HOSTPostgreSQL 服务地址，可使用容器内服务名或外部 IP。postgres
    DB_PORTPostgreSQL 服务端口。5432
    DB_DATABASEData Agent 使用的 PostgreSQL 数据库名称。mydatabase
    DB_USER连接 PostgreSQL 的账号，需包含建表、索引和扩展权限。postgres
    DB_PASSWORDPostgreSQL 对应账号的密码。postgres
    CLUSTER_MODE集群进程数，用于控制服务实例数量。默认为 4；K8s 环境建议设为 1
    TZ容器时区设置。Asia/Shanghai
    APP_KEY生产环境必须配置。用于签名和验证 JWT token 的密钥，确保用户登录状态的安全性。至少 32 字符的随机字符串
    CACHE_DEFAULT_STORE缓存类型，只能填 memory 或 redis 两个固定值之一。memory
    CACHE_EXPIRE_MODESQL 结果缓存过期模式。仅在 CACHE_DEFAULT_STORE=redis 时生效；支持 ttl 或 daily，未配置时按 ttl 处理。ttl
    CACHE_TTL_SECONDSSQL 结果缓存秒数。仅在 CACHE_DEFAULT_STORE=redis 且 CACHE_EXPIRE_MODE=ttl 时生效。10
    CACHE_EXPIRE_ATSQL 结果缓存每日过期时间。仅在 CACHE_DEFAULT_STORE=redis 且 CACHE_EXPIRE_MODE=daily 时生效；格式支持 HH:mm 或 HH:mm:ss。03:00
    REDIS_MODERedis 连接模式。默认留空表示单机模式；使用 Redis Sentinel 时填写 sentinel。sentinel
    REDIS_URLRedis 连接 URL，当使用 Redis 缓存/多进程/集群模式时需要配置。redis://localhost:6379/0
    REDIS_SENTINEL_NAMERedis Sentinel 监控的主节点名称。仅在 REDIS_MODE=sentinel 时使用。mymaster
    REDIS_SENTINEL_NODESRedis Sentinel 节点列表，多个节点用英文逗号分隔。10.0.0.1:26379,10.0.0.2:26379,10.0.0.3:26379
    REDIS_USERNAMERedis 数据节点用户名。启用 ACL 时配置。default
    REDIS_PASSWORDRedis 数据节点密码。your-redis-password
    REDIS_SENTINEL_USERNAMESentinel 节点用户名。未配置时默认复用 REDIS_USERNAME。sentinel-user
    REDIS_SENTINEL_PASSWORDSentinel 节点密码。未配置时默认复用 REDIS_PASSWORD。sentinel-password
    REDIS_DBRedis 数据库编号。单机和 Sentinel 模式都支持。0
    PUBSUB_ADAPTER_REDIS_URLPubSub 适配器的独立 Redis URL。仅单机模式下使用，未配置时回退到 REDIS_URL。redis://redis-pubsub:6379/0
    QUEUE_ADAPTER_REDIS_URL队列适配器的独立 Redis URL。仅单机模式下使用，未配置时回退到 REDIS_URL。redis://redis-queue:6379/0
    LOCK_ADAPTER_REDIS_URL分布式锁适配器的独立 Redis URL。仅单机模式下使用，未配置时回退到 REDIS_URL。redis://redis-lock:6379/0
    APP_PORT应用服务监听端口。80

    APP_KEY 安全说明

    APP_KEY 是系统安全的核心配置，务必妥善管理。

    生成方式

    APP_KEY 必须随机生成且保持固定，长度和格式无特殊要求。可使用以下命令生成：

    openssl rand -base64 32

    作用

    用于签名和验证 JWT token 的密钥，确保用户登录状态的安全性。

    原理

    • 用户登录后，服务器使用 APP_KEY 签发 JWT token
    • 后续请求携带 token，服务器用同样的 APP_KEY 验证身份
    • 只有 APP_KEY 一致，token 才能通过验证

    重要性

    • 生产环境必须显式配置固定值：不要依赖系统自动生成。在生产环境中，APP_KEY 必须通过环境变量、Secret 或其他配置中心设置为固定值，并在容器重建、扩缩容、滚动发布后保持不变
    • 未配置会导致凭证失效：如果未配置 APP_KEY，系统会在每次容器重新创建时生成一个新的随机值，过去的所有登录状态以及 API Token 都会失效
    • 必须保密：泄露后攻击者可以伪造任意用户身份
    • 必须足够复杂：建议至少 32 字符的随机字符串

    联网检索能力

    如需让 AI员工 在问答时具备联网检索能力（需要在AI员工的技能里面手动添加），可配置 WEB_SEARCH_API_KEY 环境变量，或按供应商分别设置 Tavily/Bing/SerpAPI 的 Key：

    # API Key（任选一个）
WEB_SEARCH_API_KEY=tvly-dev-xxxxxxxx

# 或者使用更具体的 Key
# TAVILY_API_KEY=your-tavily-key
# TAVILY_API_BASE_URL=https://api.tavily.com  # Tavily API 地址（可选，默认官方地址）
# BING_API_KEY=your-bing-key
# SERPAPI_API_KEY=your-serpapi-key

    缓存配置

    CACHE_DEFAULT_STORE 只能填写以下两个固定值之一，不要填写其他内容：

    重要：在多进程模式（CLUSTER_MODE > 1）或集群部署时，必须将 CACHE_DEFAULT_STORE 配置为 redis，否则各进程间的状态无法同步，会导致数据不一致和功能异常。

    内存缓存（默认）

    CACHE_DEFAULT_STORE=memory  # 固定值：memory

    Redis 缓存

    CACHE_DEFAULT_STORE=redis           # 固定值：redis（不要填写 redis 的地址或应用名）
REDIS_URL=redis://localhost:6379/0  # Redis 连接地址在这里配置

    Redis 数据结果缓存过期策略

    以下参数用于控制 Redis 模式下的数据结果缓存过期策略，其中缓存 key 为 SQL 语句。仅在 CACHE_DEFAULT_STORE=redis 时生效；未配置时按 ttl 模式处理。

    方案 A：固定 TTL（默认）

    CACHE_DEFAULT_STORE=redis
REDIS_URL=redis://localhost:6379/0

# 不配置时默认按 ttl 模式处理
CACHE_EXPIRE_MODE=ttl
CACHE_TTL_SECONDS=10

    方案 B：按每天固定时间过期

    CACHE_DEFAULT_STORE=redis
REDIS_URL=redis://localhost:6379/0

CACHE_EXPIRE_MODE=daily
CACHE_EXPIRE_AT=03:00
# 也支持写成 03:00:00

    说明：

    • CACHE_EXPIRE_MODE=ttl：缓存写入后按固定秒数过期，秒数由 CACHE_TTL_SECONDS 控制，默认 10 秒。
    • CACHE_EXPIRE_MODE=daily：缓存在每天固定时刻过期，时间点由 CACHE_EXPIRE_AT 控制。

    Redis Sentinel（高可用）

    当应用部署在多机、Kubernetes 或需要 Redis 高可用切换的生产环境时，推荐使用 Redis Sentinel。

    CACHE_DEFAULT_STORE=redis
REDIS_MODE=sentinel

# Sentinel 必填项
REDIS_SENTINEL_NAME=mymaster
REDIS_SENTINEL_NODES=10.0.0.1:26379,10.0.0.2:26379,10.0.0.3:26379

# Redis 数据节点认证（如启用 ACL）
REDIS_USERNAME=default
REDIS_PASSWORD=your-redis-password
REDIS_DB=0

# Sentinel 节点认证（如与数据节点不同，可单独设置）
# REDIS_SENTINEL_USERNAME=sentinel-user
# REDIS_SENTINEL_PASSWORD=sentinel-password

    Redis Sentinel 可选高级参数

    以下参数通常只在网络拓扑复杂、连接池容量需要调整，或 Redis 通过 NAT / Service 转发时使用。大多数场景可以不配置：

    # 主节点 / 副本节点连接池大小
# REDIS_SENTINEL_MASTER_POOL_SIZE=5
# REDIS_SENTINEL_REPLICA_POOL_SIZE=3

# Sentinel 扫描与重发现参数（单位：毫秒）
# REDIS_SENTINEL_SCAN_INTERVAL=1500
# REDIS_SENTINEL_MAX_COMMAND_REDISCOVERS=7

# 是否透传底层 client error 事件
# REDIS_SENTINEL_PASSTHROUGH_CLIENT_ERROR_EVENTS=true

# 当 Sentinel 返回的 Redis 节点地址需要映射为容器内/集群内地址时使用
# REDIS_SENTINEL_NODE_ADDRESS_MAP={\"10.0.0.10:6379\":{\"host\":\"redis-master.default.svc\",\"port\":6379}}

    Redis 角色级 URL 覆盖

    在单机 Redis 模式下，如果希望为不同组件指定不同的 Redis 实例，可分别配置以下变量；未配置时会统一回退到 REDIS_URL：

    PUBSUB_ADAPTER_REDIS_URL=redis://redis-pubsub:6379/0
QUEUE_ADAPTER_REDIS_URL=redis://redis-queue:6379/0
LOCK_ADAPTER_REDIS_URL=redis://redis-lock:6379/0

    注意：当 REDIS_MODE=sentinel 时，系统会统一从 REDIS_SENTINEL_* 变量构造连接配置，上述 *_REDIS_URL 不再生效。

    端口配置

    通过 APP_PORT 环境变量设置服务监听端口，默认值为 80。

    配置示例

    APP_PORT=13000

    注意：在容器化部署时，修改端口后需同步更新 docker-compose.yml 中的 ports 映射或 Kubernetes 的 Service 端口配置。

    SSH 隧道

    当目标数据库无法直接访问时，可以通过 SSH 隧道（跳板机）进行连接。配置以下环境变量即可启用 SSH 隧道功能：

    # SSH 隧道配置
SSH_HOST=jump-server.example.com    # 跳板机地址
SSH_PORT=2222                       # SSH 端口，默认 22
SSH_USER=ssh-user                    # SSH 登录用户名
SSH_PASSWORD=ssh-password            # SSH 登录密码

# 或者使用私钥认证（推荐）
SSH_PRIVATE_KEY_PATH=/path/to/.ssh/id_rsa    # 私钥文件路径
SSH_PASSPHRASE=key-password                  # 私钥密码（如果有）

# 调试模式（可选，用于排查连接问题）
SSH_DEBUG=1

    配置说明

    变量说明必填
    SSH_HOST跳板机 IP 地址或域名是
    SSH_PORTSSH 服务端口，默认为 22否
    SSH_USERSSH 登录用户名是
    SSH_PASSWORDSSH 登录密码与私钥二选一
    SSH_PRIVATE_KEY_PATH私钥文件的绝对路径与密码二选一
    SSH_PASSPHRASE私钥的解密密码否
    SSH_DEBUG启用调试日志，值为 1 时开启否

    注意事项

    • 密码和私钥认证方式二选一，推荐使用私钥认证更安全
    • 私钥文件路径必须是容器内的绝对路径，需要通过 Docker Volume 挂载
    • 开启 SSH_DEBUG=1 后会在日志中输出详细的连接信息，便于排查问题

    跨域资源权限配置

    如果安全扫描工具提示跨域资源权限问题，需要配置相关环境变量，指定允许的跨域来源。

    配置示例

    CORS_ORIGIN_WHITELIST=https://app.example.com,https://admin.example.com # 允许的跨域来源，多个来源用逗号分隔，精准匹配

    推荐配置方式

    Docker/Compose

    1. 在部署目录创建 .env，写入上述变量：

      PROJECT=prod-agent
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=data_agent
DB_USER=postgres
DB_PASSWORD=strongPassw0rd

    2. 在 docker-compose.yml 中引用：

      services:
  app:
    image: yiask/dataagent:latest
    env_file:
      - ./.env

    使用 env_file 可以避免在 Compose 文件中暴露敏感信息，并方便不同环境复用同一份模板。

    Kubernetes/云原生

    1. 将变量写入 Secret：

      apiVersion: v1
kind: Secret
metadata:
  name: data-agent-env
stringData:
  PROJECT: prod-agent
  DB_HOST: postgres.default.svc.cluster.local
  DB_PORT: "5432"
  DB_DATABASE: data_agent
  DB_USER: postgres
  DB_PASSWORD: strongPassw0rd

    2. 在 Deployment 中挂载：

      envFrom:
  - secretRef:
      name: data-agent-env

    调整与排查

    • 连接失败：确认 DB_HOST 可达并允许 DB_USER 访问，必要时在容器内执行 psql -h $DB_HOST 测试。
    • 多项目部署：为不同实例设置唯一的 PROJECT，便于日志、监控和文件目录隔离。
    • 修改密码：更新数据库密码后务必同步更新对应 Secret/.env 并重新滚动发布。

    配置完成后，可继续阅读《单台服务器部署》或 K8s 部署 获取完整的部署流程。