企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 编排
• RPA
• 后端
• 前端
• 企业应用

AstronAgent 是一套面向企业级 Agent 工作流平台的完整开源方案，本文基于仓库中的 DEPLOYMENT_GUIDE_WITH_AUTH_RPA.md 编写，围绕「身份认证 + 知识库 + 核心业务 + RPA 自动化」四类组件的 Docker Compose 集成部署展开。读完本文，你将掌握 AstronAgent 与 Casdoor、RagFlow、astronRPA 的正确启动顺序、环境变量配置、平台账号体系接入方式，以及升级与安全预检的运维要点，可直接照搬到测试与生产环境。

项目架构概述：一条命令拉起四大组件

AstronAgent 的认证化 + RPA 部署形态由四个主要组件构成：

1. Casdoor—— 身份认证和单点登录服务（必要组件，为控制台与各核心服务提供统一认证）
2. RagFlow—— 知识库和文档检索服务（非必要组件，按需部署，为 Agent 提供 RAG 检索增强能力）
3. AstronAgent—— 核心业务服务集群（必要组件，包含 Agent、Workflow、Knowledge、Tenant、Console 等一组服务）
4. RPA—— 企业级机器人流程自动化服务（后端自动化部署，随核心服务一起拉起）

这一部署形态对应仓库根目录下的 docker-compose-with-auth-rpa.yaml。从该文件源码可见，它并不是一份从头编写的清单，而是通过 Docker Compose 的include机制把三份独立的编排文件组合为一个整体（见 docker-compose-with-auth-rpa.yaml）：

include: # Casdoor 认证服务 - path: docker-compose-auth.yml env_file: - .env # astronAgent 核心服务 - path: docker-compose.yaml env_file: - .env.with-rpa - .env # astronRPA 服务 - path: astronRPA/docker-compose.yml project_directory: astronRPA env_file: - .env - astronRPA/.env

三个子清单（docker-compose-auth.yml、docker-compose.yaml、astronRPA/docker-compose.yml）中的所有服务统一接入同一个名为astron-agent-network的 bridge 网络，既避免了多个 include 之间的网络冲突，也让容器之间可以通过服务名直接互通。如果你只需要「认证 + 核心服务」而不需要 RPA，仓库还提供了精简版 docker-compose-with-auth.yaml，它只 include 认证与核心服务两份清单。

前置要求

部署前先核对宿主机资源。Agent 系统与 RAGFlow 对资源的要求不同，可按需分配：

同时确认宿主机已安装Docker与Docker Compose（Compose 需要支持include机制与config --format json，新版 Docker Compose v2 均可满足）。

第一步：启动 RagFlow 知识库服务（可选）

RagFlow 是一个开源 RAG（检索增强生成）引擎，通过深度文档理解技术为 Agent 提供知识库问答能力。它是按需部署的组件：如果 Agent 的知识库平台选择「星火知识库」而非 RagFlow，则可以跳过本节。

启动方式：运行 docker/ragflow/docker-compose.yml（Linux）或 docker/ragflow/docker-compose-macos.yml（macOS）。

# 进入 RagFlow 目录 cd docker/ragflow # 给所有 sh 文件添加可执行权限 chmod +x *.sh # 启动 RagFlow 服务（包含所有依赖） docker compose up -d # 查看服务状态 docker compose ps # 查看服务日志 docker compose logs -f ragflow

访问地址：RagFlow Web 界面http://localhost:18080。

模型配置步骤：

1. 点击头像进入Model Providers（模型提供商）页面，选择Add Model（添加模型），填写对应的API 地址和API Key，分别添加Chat 模型和Embedding 模型。
2. 在同一页面右上角点击Set Default Models（设置默认模型），将上一步添加的Chat 模型与Embedding 模型设为默认。

重要配置说明：

• 默认使用 Elasticsearch 作为文档引擎，如需切换到 opensearch、infinity，请修改.env中的DOC_ENGINE配置；
• 支持 GPU 加速：使用仓库中的 docker/ragflow/docker-compose-gpu.yml 启动即可。

第二步：配置 AstronAgent 环境变量

在启动核心服务之前，需要先准备.env文件，它承载服务启动、访问地址、认证、数据库、Redis、对象存储等基础设施参数。

# 进入 astronAgent 目录 cd docker/astronAgent # 创建仅部署用户可读写的环境变量文件 install -m 600 .env.example .env

install -m 600会把权限收紧到仅部署用户可读写，避免凭据泄露。需要特别注意的是：RAGFlow、讯飞开放平台、AI Ability Chat、虚拟人能力、星火知识库等业务能力账号不再写入.env，请在 AstronAgent 启动后登录控制台，通过平台账号管理页面配置（详见第四步）。

2.1 配置服务主机地址

vim .env

在.env中配置 AstronAgent 服务的主机地址：

HOST_BASE_ADDRESS=http://localhost

说明：

• 如果使用域名访问，请将localhost替换为你的域名；
• 仅向用户公开 AstronAgent 的应用入口（Nginx/Ingress）；
• 内置 MinIO 的 API 与管理控制台必须保持安全默认值：Docker Compose 仅绑定宿主机回环地址（见 docker-compose.yaml，端口127.0.0.1:18998与127.0.0.1:18999），Helm 部署则使用ClusterIP。只有存在明确的运维需求，并配置独立认证、TLS 与网络策略/防火墙限制时，才可显式开放相应端点；禁止将 MinIO 直接发布到互联网。

2.2 准备业务能力账号信息（启动后在页面配置）

以下配置不需要写入.env。启动 AstronAgent 后，登录控制台，在左侧菜单进入平台账号管理，按卡片填写即可；保存后全局生效，不需要重启容器。如果某个功能依赖对应能力但尚未配置，系统会提示前往平台账号管理配置，不会阻塞系统启动。

讯飞开放平台（内置星火模型、实时语音转写、图片生成等能力会使用）：需要准备以下字段：

AI Ability Chat（Agent 内部默认模型接口，OpenAI 协议）：

• AI_ABILITY_CHAT_BASE_URL
• AI_ABILITY_CHAT_MODEL
• AI_ABILITY_CHAT_API_KEY

虚拟人能力：

• SPARK_VIRTUAL_MAN_APP_ID
• SPARK_VIRTUAL_MAN_API_KEY
• SPARK_VIRTUAL_MAN_API_SECRET

知识库平台：

• RagFlow：RAGFLOW_BASE_URL、RAGFLOW_API_TOKEN、RAGFLOW_TIMEOUT、RAGFLOW_DEFAULT_GROUP
• 星火知识库：XINGHUO_DATASET_ID

创建知识库时会选择使用RagFlow或星火知识库，只需要配置实际使用的平台即可。

获取 RagFlow API Token：

1. 访问 RagFlow Web 界面http://localhost:18080；
2. 登录后点击头像进入用户设置；
3. 点击 API 生成 API KEY；
4. 在平台账号管理 - 知识库平台中填写到RAGFLOW_API_TOKEN。

获取星火知识库数据集 ID：星火 RAG 云服务提供两种使用方式：

方式一：在页面中获取。使用讯飞开放平台创建的 APP_ID 和 API_SECRET，直接在页面中获取星火数据集 ID，详见仓库内的 xinghuo_rag_tool.html。

方式二：cURL 命令行方式。通过以下命令创建数据集：

# 创建星火RAG数据集 curl -X PUT 'https://chatdoc.xfyun.cn/openapi/v1/dataset/create' \ -H "Accept: application/json" \ -H "appId: your_app_id" \ -H "timestamp: $(date +%s)" \ -H "signature: $(echo -n "$(echo -n "your_app_id$(date +%s)" | md5sum | awk '{print $1}')" | openssl dgst -sha1 -hmac 'your_api_secret' -binary | base64)" \ -F "name=我的数据集"

注意事项：

• 请将your_app_id替换为你的实际 APP ID；
• 请将your_api_secret替换为你的实际 API Secret。

获取到数据集 ID 后，请在平台账号管理 - 知识库平台中填写到XINGHUO_DATASET_ID。

第三步：启动 AstronAgent 核心服务（包含 Casdoor 认证服务与 RPA 后端服务）

启动 AstronAgent 服务请运行 docker-compose-with-auth-rpa.yaml。该文件已通过include机制集成了 Casdoor 与 RPA 后端服务，会自动启动 Casdoor、RPA 及核心服务集群。

# 进入 astronAgent 目录 cd docker/astronAgent # 变更服务前，先校验完整渲染后的凭据共享与健康检查契约 python3 scripts/verify_security_contract.py --compose-file docker-compose-with-auth-rpa.yaml # 启动所有服务（包含 Casdoor 和一次性 RPA atlas 任务） docker compose -f docker-compose-with-auth-rpa.yaml up -d

关于安全契约预检：该脚本（scripts/verify_security_contract.py）会先执行docker compose config --format json渲染出最终 Compose 清单，然后校验：内部凭据（workflow 内部 API Key、tenant 引导凭据）必须通过命名卷以文件/属性方式注入且禁止内联、internal-credentials-init一次性任务必须network_mode: none且restart: no、核心服务必须依赖其service_completed_successfully、console-hub健康检查必须启用且被core-agent/core-workflow以service_healthy依赖（见 verify_security_contract.py）。脚本还内置了 22 个负向自测用例与 shell 凭据生命周期演练，确保即使配置被误改，错误信息也永远不会序列化敏感值（见 verify_security_contract.py）。预检通过后会输出security contract gate: PASS。

说明：

• Casdoor 默认登录账户名：admin，密码：123；
• 升级时必须让检出的 Compose 清单与应用镜像同步更新。docker compose pull只更新镜像，不会更新docker-compose.yaml；停止现有服务前应运行仓库提供的部署契约预检，并保留.env与命名卷。常规升级禁止使用down -v（-v会删除命名卷，导致内部凭据与数据库数据丢失）。

启动后你会得到什么：一次拉起约 20 个容器

从三份 include 清单的源码可以完整还原启动后的服务拓扑：

认证（docker-compose-auth.yml）：

• casdoor：镜像casbin/casdoor:v2.67.0，端口映射${CASDOOR_PORT:-8000}:8000；
• casdoor-mysql：MySQL 8.4.6，承载 Casdoor 自身数据。

Casdoor 容器启动时会执行 casdoor/entrypoint.sh：把app.conf复制到运行时目录，并用sed将init_data.json.template中的${CONSOLE_DOMAIN}、${HOST_BASE_ADDRESS}渲染为实际值，写入redirectUris: [${CONSOLE_DOMAIN}/callback, ${HOST_BASE_ADDRESS}/callback]后以--createDatabase=true启动。模板（casdoor/conf/init_data.json.template）预置了组织example-org与应用example-app，保证开箱即用。

核心服务（docker-compose.yaml）：

• 基础设施：postgres（14）、mysql（8.4.6）、redis（7）、minio（API/控制台仅绑定回环地址）、internal-credentials-init（一次性凭据生成任务）、minio-credentials-check（对象存储凭据一致性校验）；
• 业务集群：core-tenant（5052）、core-database（7990）、core-rpa（17198）、core-link（18888）、core-aitools（18668）、core-agent（17870）、core-knowledge（20010）、core-workflow（7880）；
• 控制台：nginx（默认 80 端口）、console-frontend（内部 1881）、console-hub（内部 8080）。

RPA（astronRPA/docker-compose.yml）：

• 基础设施：rpa-mysql（8.4.6，挂载volumes/mysql/下的 schema 与初始化 SQL）、rpa-atlas（一次性任务，用 Ariga Atlas 依据volumes/atlas/schema.hcl执行schema apply）、rpa-redis、rpa-minio；
• 业务服务：ai-service、openapi-service、resource-service、robot-service、rpa-auth（均为ghcr.io/iflytek/astron-rpa/*镜像），统一由openresty-nginx反向代理到宿主端口32742。

第四步：配置平台账号管理（可选，按需配置业务能力）

AstronAgent 启动后，访问控制台并登录，在左侧菜单进入平台账号管理。该菜单与应用管理、资源管理同级，包含四个配置卡片：

1. 讯飞开放平台：填写PLATFORM_APP_ID、PLATFORM_API_KEY、PLATFORM_API_SECRET、SPARK_API_PASSWORD、SPARK_RTASR_API_KEY；
2. AI Ability Chat：填写AI_ABILITY_CHAT_BASE_URL、AI_ABILITY_CHAT_MODEL、AI_ABILITY_CHAT_API_KEY；
3. 虚拟人能力：填写SPARK_VIRTUAL_MAN_APP_ID、SPARK_VIRTUAL_MAN_API_KEY、SPARK_VIRTUAL_MAN_API_SECRET；
4. 知识库平台：分别填写 RagFlow 的RAGFLOW_BASE_URL、RAGFLOW_API_TOKEN、RAGFLOW_TIMEOUT、RAGFLOW_DEFAULT_GROUP，以及星火知识库的XINGHUO_DATASET_ID。

保存配置后会立即全局生效，系统会自动刷新缓存，不需要重启 AstronAgent 容器。

第五步：修改 Casdoor 认证（可选）

系统已预置默认组织与应用，可以直接使用；如果需要定制，可在 Casdoor 中创建新的组织和应用，并把配置信息更新到.env中。

5.1 配置 Casdoor 应用

获取 Casdoor 配置信息：

1. 访问 Casdoor 管理控制台：http://localhost:8000；
2. 使用默认管理员账号登录：admin / 123；
3. 创建组织：进入http://localhost:8000/organizations页面，点击「添加」，填写组织名称后保存并退出；
4. 创建应用并绑定组织：进入http://localhost:8000/applications页面，点击「添加」，填写：
   • Name：自定义应用名称，例如agent；
   • Redirect URL：设置为项目的回调地址。如果 Nginx 暴露的端口号是80，使用http://your-local-ip/callback；如果是其他端口（例如888），使用http://your-local-ip:888/callback；
   • Organization：选择刚创建的组织名称；
5. 保存应用后，记录以下信息并与项目配置项一一对应：

6. 将以上配置信息填写到项目的环境变量文件中：

cd docker/astronAgent vim .env

在.env文件中添加或更新以下配置项：

# Casdoor配置 CONSOLE_CASDOOR_URL=http://localhost:8000 CONSOLE_CASDOOR_ID=your-casdoor-client-id CONSOLE_CASDOOR_APP=your-casdoor-app-name CONSOLE_CASDOOR_ORG=your-casdoor-org-name

7. 重启 AstronAgent 服务以应用新配置：

docker compose restart console-frontend console-hub

从 docker-compose.yaml 可见，console-frontend与console-hub正是消费CONSOLE_CASDOOR_*四个变量的服务，因此只需重启这两个容器即可让认证配置生效，无需重启整个集群。

服务访问地址

启动完成后，通过以下地址访问各项服务：

运维与排障要点

日志排查：容器日志是首要排障入口，使用docker compose -f docker-compose-with-auth-rpa.yaml logs -f <service>观察具体服务。仓库为各核心服务挂载了宿主机日志目录（如docker/astronAgent/config/agent/logs/、config/workflow/logs/等），可直接在宿主机侧查看。

健康检查：多数核心服务（console-hub、core-agent、core-workflow、core-knowledge）都定义了healthcheck，其中core-agent、core-workflow、core-knowledge通过 Python 探测各自端口的/health/ready，console-hub通过curl探测http://localhost:8080/health，可用docker compose ps观察各容器健康状态。

网关与 SSE：控制台对外流量统一经过 nginx/nginx.conf：/console-api/反代到console-hub:8080，其余请求打到console-frontend:1881；工作流聊天接口/workflow/v1/chat/completions与/workflow/v1/resume走 SSE 长连接代理（30 分钟读写超时、关闭缓冲），并先经内部auth_request子请求完成网关鉴权，而/workflow/v1/下其余内部 API 一律返回 404，不对外暴露（见 nginx.conf）。

升级规范：升级前先运行python3 scripts/verify_security_contract.py --compose-file docker-compose-with-auth-rpa.yaml完成契约预检；升级过程只更新镜像与 Compose 清单，务必保留.env与命名卷，禁止使用down -v。

安全基线：遵循「仅暴露必要入口」的原则——对外只开放 Nginx（80/443）与 RPA OpenResty（32742），Casdoor 管理台（8000）、RagFlow（18080）、MinIO（18998/18999）等服务保持内网访问；内部凭据由一次性任务生成并持久化在独立命名卷中，不写入环境变量明文。

首次部署建议在测试环境中验证全部功能后再迁移到生产环境。部署过程中如遇到问题，请优先查看相关服务的日志文件，再对照仓库中的部署文档（docs/zh/DEPLOYMENT_GUIDE_WITH_AUTH_RPA.md、docs/zh/DEPLOYMENT_GUIDE.md、docs/zh/DEPLOYMENT_FAQ.md）与 faq/troubleshooting.md 排查。

• 人工智能
• AI Agent
• Agent 编排
• RPA
• 后端
• 前端
• 企业应用