单台服务器部署

本文档以 CentOS 为例介绍 Data Agent 的单台服务器部署流程。其他 Linux 发行版可使用类似命令替代。

前置条件

服务器需具备 sudo 权限
已阅读环境变量文档

机器推荐配置

项目	最低	推荐
CPU	4 核	16 核及以上
Linux 内核版本	3.10 及以上	3.10 及以上
位数	64 位	64 位
内存	8GB	32GB 及以上
硬盘（要求固态）	30GB 及以上	60GB 及以上

1. 安装 Docker

1.1 Linux 在线安装

参考 Docker 官方文档：Install Docker Engine on CentOS

1.2 Linux 离线安装

如服务器无法访问外网，可使用离线安装方式。

注意

仅支持 x86_64 架构的 Linux 服务器。

1. 下载离线安装文件

下载以下三个文件并放置在同一目录下：

文件	下载地址
Docker 离线安装包	docker-27.5.1.tgz
Docker Compose	docker-compose-linux-x86_64
安装脚本	docker-install.sh（见下方折叠内容）

注意

下方文档不可以直接从文档复制到服务器，需要先在本地编辑器上编辑好格式，

直接使用vim编辑可能存在 ”\r”，“^M” 等不可见字符，导致安装脚本运行失败

docker-install.sh 脚本内容（点击展开）

#!/bin/bash

set -e  # 遇到错误即退出

# 设置文件名
docker_file="docker-27.5.1.tgz"
docker_compose_file="docker-compose-linux-x86_64"

# 检查架构
ARCH=$(uname -m)
if [ "$ARCH" != "x86_64" ]; then
    echo "当前服务器的架构是: $ARCH，仅支持x86_64架构"
    exit 1
fi

echo "当前服务器的架构是 x86_64 (64-bit)，继续进行"


install_docker(){
    # 检查文件是否存在（内网环境，不进行下载，仅检查文件是否存在）
    if [[ ! -f "$docker_file" || ! -f "$docker_compose_file" ]]; then
        echo "错误：未在当前目录找到必要的安装文件！"
        echo "请确保 $docker_file 和 $docker_compose_file 已放置在脚本同路径下"
        exit 1
    fi

    # 执行离线安装 Docker
    offline_install() {
        local origin_path=$(pwd)  # 记录当前目录
        file_path=$(pwd)  # 设置离线文件所在目录为当前目录

        # 解压 Docker 文件并安装
        cd $file_path
        tar xzvf $docker_file
        cp -rf docker/* /usr/bin/  # 复制 Docker 可执行文件到 /usr/bin/
        rm -rf docker  # 删除解压后的临时文件
        cd ${origin_path} >/dev/null  # 回到原来的目录
    }

    # 写入 Docker systemd 服务配置
    write_service() {
        mkdir -p /usr/lib/systemd/system/

        # 定义 Docker 服务配置内容
        docker_service_config="[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
After=network-online.target firewalld.service
Wants=network-online.target

[Service]
Type=notify
ExecStart=/usr/bin/dockerd
ExecReload=/bin/kill -s HUP \$MAINPID
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
TimeoutStartSec=0
Delegate=yes
KillMode=process
Restart=on-failure
StartLimitBurst=3
StartLimitInterval=60s

[Install]
WantedBy=multi-user.target"

        # 将服务配置内容写入 docker.service 文件
        echo "$docker_service_config" > /usr/lib/systemd/system/docker.service
    }

    # 执行离线安装步骤
    offline_install
    write_service
    systemctl daemon-reload

    # 安装 Docker Compose
    mv $docker_compose_file docker-compose
    mv docker-compose /usr/local/bin/
    chmod +x /usr/local/bin/docker-compose

    # 判断是否存在 systemctl
    if command -v systemctl &>/dev/null; then
        # 启用并重启 Docker 服务
        systemctl enable docker.service
        systemctl restart docker
    else
        echo "未找到 systemctl，无法管理 Docker 服务。"
    fi

    echo "Docker 和 Docker Compose 安装完成！"
}


# 检查 docker 是否存在
if ! command -v docker &> /dev/null; then
    echo "未安装 Docker，开始安装..."
    install_docker && echo "Docker 安装完成"
else
    echo "Docker 已安装，版本：$(docker --version)"
    # 检查 docker compose（支持新版和旧版）
    if command -v docker-compose &> /dev/null; then
        echo "安装了旧版 docker-compose，版本：$(docker-compose --version)"
    elif docker compose version &> /dev/null; then
        echo "安装了新版 Docker Compose，版本：$(docker compose version --short)"
    else
        echo "未安装 Docker Compose，开始安装..."
        install_docker && echo "Docker Compose 安装完成"
    fi
fi

echo "所有任务执行完毕！"

2. 执行安装脚本

# 赋予脚本执行权限
chmod +x docker-install.sh

# 执行安装脚本
sudo ./docker-install.sh

脚本会自动完成以下操作：

解压并安装 Docker
配置 Docker systemd 服务
安装 Docker Compose
启动 Docker 并设置开机自启

1.3 验证安装

# 检查 Docker 是否正常运行
sudo docker ps

# 检查 Compose 插件是否安装
sudo docker-compose --version

# 设置开机自启（如未设置）
sudo systemctl enable docker

如上述命令均显示正常输出，则 Docker 安装完成。

如果服务器无法直接访问镜像仓库，需要离线准备 yiask、redis、pg 镜像包，可继续阅读：离线镜像包准备。

2. 系统环境配置

2.1 时区设置

确保服务器时区正确，避免时间相关功能异常：

# 查看当前时区
timedatectl

# 设置为上海时区
sudo timedatectl set-timezone Asia/Shanghai

# 确认设置结果
timedatectl

2.2 安装 Git（可选）

sudo yum install git

2.3 白名单配置

若需对接办公系统或启用语音服务，请开放以下域名白名单：

服务	域名
企业微信	`qyapi.weixin.qq.com`
飞书	`open.feishu.cn`
语音服务	`nls-meta.cn-shanghai.aliyuncs.com` `nls-gateway.cn-shanghai.aliyuncs.com`

3. 启动服务

创建 docker-compose.yml 文件：

services:
  app:
    image: yiask/dataagent:2.0.0  # 版本号从文档最后获取最新版本
    # 国内环境可使用：image: docker.1ms.run/yiask/dataagent:latest
    container_name: yiask
    environment:
      - PROJECT=testYiask
      - LOGGER_LEVEL=error
      - TZ=Asia/Shanghai
      # APP_KEY 用于 JWT token 签名验证，必须随机生成且保持固定（长度、格式无特殊要求。示例生成指令：openssl rand -base64 32）
      - APP_KEY=your-random-app-key-here
      # PG元数据库的配置
      - DB_HOST=postgres
      - DB_DATABASE=mydatabase
      - DB_USER=postgres
      - DB_PASSWORD=postgres

      # 缓存配置（可选，默认使用内存缓存）
      - CACHE_DEFAULT_STORE=redis

      # 多进程状态同步（生产环境必选，单机 Redis 示例）
      - REDIS_URL=redis://redis:6379/0

      # 如果接入外部 Redis Sentinel，请改用以下配置，并删除上面的 REDIS_URL
      # - REDIS_MODE=sentinel
      # - REDIS_SENTINEL_NAME=mymaster
      # - REDIS_SENTINEL_NODES=10.0.0.1:26379,10.0.0.2:26379,10.0.0.3:26379
      # - REDIS_USERNAME=default
      # - REDIS_PASSWORD=your-redis-password
      # - REDIS_DB=0

      # 网页搜索 API Key（可选）
      # - WEB_SEARCH_API_KEY=tvly-dev-xxxxxxxx
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost/api/v1/__health_check"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    volumes:
      - storage:/app/nocobase/storage
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "3052:80"
    init: true
    extra_hosts:
      - "host.docker.internal:host-gateway"

  postgres:
    container_name: yiask_postgres
    image: pgvector/pgvector:pg17-trixie
    # 国内环境可使用：image: docker.1ms.run/pgvector/pgvector:pg17-trixie
    restart: always
    command: postgres -c wal_level=logical
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 10
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: mydatabase
    volumes:
      - pg-data:/var/lib/postgresql/data

  redis:
    container_name: yiask_redis
    image: redis:8.4
    # 国内环境可使用：image: docker.1ms.run/redis:8.4
    restart: always
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - redis-data:/data

volumes:
  storage:
  pg-data:
  redis-data:

保存文件后执行 docker compose up -d 即可启动所有依赖服务。

如果 Redis 由外部高可用集群提供，而不是当前 Compose 内置的 redis 服务，请删除 Compose 中的 redis 服务定义与 depends_on.redis 配置，并改为使用环境变量文档中的 Redis Sentinel 参数。

说明：2.0.6 及以上版本默认只需要持久化 /app/nocobase/storage。/app/nocobase 根目录中的运行时文件不需要单独持久化；只有在启用只读文件系统时，才需要为 /app/nocobase 额外挂载一个可写卷。如果同时挂载这两个路径，必须先声明 /app/nocobase/storage，再声明 /app/nocobase。

4. 健康检查

4.1 应用健康检查端点

系统提供健康检查端点用于监控服务状态：

端点	方法	响应
`/api/v1/__health_check`	GET	`200` + `ok`

使用示例：

# 已进入容器后执行
curl http://localhost:80/api/v1/__health_check; echo

# 宿主机检查（假设端口映射为 3052）
curl http://localhost:3052/api/v1/__health_check; echo

4.2 服务状态查看

# 查看所有容器健康状态
docker compose ps

# 查看应用健康检查日志
docker inspect yiask --format='{{json .State.Health}}' | jq

4.3 Docker Compose 健康检查配置

上文 docker-compose.yml 中已为所有服务配置健康检查：

app 服务：每 30 秒检查一次 /api/v1/__health_check 端点
postgres 服务：每 5 秒检查数据库连接
redis 服务：每 5 秒检查缓存连接

当服务健康检查失败时，Docker 会自动重启容器。

5. 只读文件系统的容器

部分客户的生产环境需要将容器文件系统设置为只读。对于 2.0.6 及以上版本，建议按下面方式拆分挂载：

注意：/app/nocobase/storage 和 /app/nocobase 是父子目录，配置 Compose volumes 时必须先声明 /app/nocobase/storage，再声明 /app/nocobase，否则子目录挂载可能被父目录覆盖。新版本中 PM2 运行时已经位于 /app/nocobase 下，不需要再额外挂载其他运行时目录。

5.1 映射 `/app/nocobase/storage` 到持久化 Volume

将 /app/nocobase/storage 继续挂载到持久化卷，用于保存上传文件、日志等业务数据：

services:
  app:
    # ... 其他配置
    volumes:
      - storage:/app/nocobase/storage

volumes:
  storage:

5.2 映射 `/app/nocobase` 到可写 Volume

将 /app/nocobase 根目录挂载到独立的可写卷，用于存储应用启动和运行过程中的临时文件：

services:
  app:
    # ... 其他配置
    volumes:
      - storage:/app/nocobase/storage
      - nocobase-root:/app/nocobase
    # 设置容器根文件系统为只读（可选）
    # read_only: true
    # tmpfs:
    #   - /tmp

volumes:
  storage:
  nocobase-root:

5.3 完整配置示例

services:
  app:
    image: yiask/dataagent:latest
    container_name: yiask
    environment:
      - PROJECT=testYiask
      - TZ=Asia/Shanghai
      - APP_KEY=your-random-app-key-here
      - DB_HOST=postgres
      - DB_DATABASE=mydatabase
      - DB_USER=postgres
      - DB_PASSWORD=postgres
    volumes:
      - storage:/app/nocobase/storage
      - nocobase-root:/app/nocobase
    # 可选：启用只读文件系统
    # read_only: true
    # tmpfs:
    #   - /tmp
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "3052:80"

volumes:
  storage:
  nocobase-root:

注意：启用只读文件系统时，确保 /app/nocobase/storage 已挂载到持久化卷，并在 volumes 列表中先声明 /app/nocobase/storage，再声明 /app/nocobase。

#单台服务器部署

#机器推荐配置

#1. 安装 Docker

#1.1 Linux 在线安装

#1.2 Linux 离线安装

#1.3 验证安装

#2. 系统环境配置

#2.1 时区设置

#2.2 安装 Git（可选）

#2.3 白名单配置

#3. 启动服务

#4. 健康检查

#4.1 应用健康检查端点

#4.2 服务状态查看

#4.3 Docker Compose 健康检查配置

#5. 只读文件系统的容器

#5.1 映射 /app/nocobase/storage 到持久化 Volume

#5.2 映射 /app/nocobase 到可写 Volume

#5.3 完整配置示例