• 简体中文

    • 环境变量

    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
    REDIS_URLRedis 连接 URL，当使用 Redis 缓存/多进程/集群模式时需要配置。redis://localhost: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 必须保持不变，否则所有用户需要重新登录
    • 必须保密：泄露后攻击者可以伪造任意用户身份
    • 必须足够复杂：建议至少 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 连接地址在这里配置

    端口配置

    通过 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 后会在日志中输出详细的连接信息，便于排查问题

    推荐配置方式

    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: chatbi/yiask: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 部署 获取完整的部署流程。