企业官网建设流程全解析

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

本文是 Astron Agent（企业级智能体工作流平台）部署选型与落地实施的入口指南。文章先帮助你在 Docker Compose 与 Helm/Kubernetes 两条路径之间做出正确选择，再基于仓库内的标准部署、带鉴权部署、带鉴权与 RPA 部署三套完整指南，给出从环境准备、Casdoor 认证集成、核心服务启动到业务能力配置的端到端实操步骤，并深入 Compose 清单与 Helm Chart 的源码细节，让读者既能「先快速跑起来」，也能「再逐步生产化」。

一、部署方式选型：两条路径，一个原则

Astron Agent 官方推荐的接入节奏是「先快速体验、再逐步生产化」。为此，仓库把部署入口收敛为两种主流方式，避免使用者一开始就陷在大量细节中迷路。

Docker Compose：本地体验与联调首选

适合本地体验、功能验证和小规模团队联调，典型场景是产品演示、研发联调与初次验证架构链路。

• 优点：启动快、上手门槛低，适合本地和测试环境
• 启动入口：docker-compose.yaml（核心服务）、docker-compose-with-auth.yaml（带 Casdoor 鉴权）、docker-compose-with-auth-rpa.yaml（带鉴权与 RPA）
• 推荐入口：快速开始

Helm / Kubernetes：面向生产的标准化部署

适合后续面向生产环境的标准化部署与扩容，典型场景是企业集群部署、持续交付与环境隔离。

• 优点：更适合多实例、弹性伸缩和统一运维
• 相关目录：helm/astron-agent，其中 Chart.yaml 定义了astron-agent（AI Agent Builder Platform with Authentication）这一 Helm Chart
• 从 Chart 的values.yaml可以看到，生产化主要围绕三件事展开：镜像仓库与版本管理（global.imageRegistry: ghcr.io/iflytek/astron-agent、global.astronAgentVersion: latest）、密钥的预创建与轮换（workflowInternalAuth、tenantBootstrap、minio.auth.existingSecret等），以及基础设施的持久化与资源配额（PostgreSQL、MySQL、Redis 均可配置persistence.size与resources.limits）

选型速查

二、部署前准备：基础设施、模型接入与鉴权决策

在动手之前，需要先完成四类决策，它们直接决定你选择哪份部署文档：

1. 基础设施：准备数据库、缓存、对象存储等基础设施。使用 Docker Compose 一键部署时，仓库已内置 PostgreSQL 14、MySQL 8.4、Redis 7 与 MinIO，无需单独搭建；只有使用外部中间件时才需要修改环境变量指向外部地址
2. 模型接入与密钥管理：确认模型接入方式和密钥管理策略。模型能力账号（讯飞开放平台、AI Ability Chat、虚拟人、知识库平台）在 Astron Agent 启动后通过控制台「平台账号管理」页面配置，不写入.env；.env仅承载服务启动、访问地址、认证、数据库、Redis、对象存储等基础设施参数
3. 鉴权需求：根据是否需要登录鉴权，选择标准部署（不带 Casdoor）或带鉴权部署（集成 Casdoor）
4. 扩展能力：明确是否需要接入 RPA、插件（Link/AITools）和租户能力

同时请核对最低硬件要求（来源于仓库部署文档）：

• Agent 系统：CPU ≥ 2 Core，RAM ≥ 4 GiB，Disk ≥ 50 GB
• RAGFlow（如启用）：CPU ≥ 4 Core，RAM ≥ 16 GB，Disk ≥ 50 GB

三、三条部署路径详解：标准 / 带鉴权 / 带鉴权 + RPA

仓库在 docs/zh 下提供了三份相互配套的完整部署指南，本文按「由简到繁」的顺序组织：

从源码看，带鉴权与带 RPA 的 Compose 文件都通过 Docker Compose 的include机制组合基础清单。以 docker-compose-with-auth.yaml 为例，它仅声明两行：

include: - docker-compose-auth.yml # Casdoor 认证服务 - docker-compose.yaml # astronAgent 核心服务

这意味着 Casdoor 与核心服务共享同一个astron-agent-network网络，无需额外手工打通网络；docker-compose-with-auth-rpa.yaml在此基础上再包含 RPA 相关服务。

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

RagFlow 是开源 RAG（检索增强生成）引擎，使用深度文档理解技术提供问答服务。如果业务需要知识库能力，从 docker/ragflow 目录启动：

cd docker/ragflow chmod +x *.sh docker compose up -d docker compose ps # 查看服务状态 docker compose logs -f ragflow # 查看服务日志

• 访问地址：RagFlow Web 界面http://localhost:18080
• 模型配置：进入 Model Providers 页面添加 Chat 模型和 Embedding 模型的 API 地址与 API Key，然后在页面右上角 Set Default Models 设为默认
• 重要配置：默认使用 Elasticsearch 作为文档引擎，如需 opensearch、infinity，修改.env中的DOC_ENGINE；支持 GPU 加速，可用docker-compose-gpu.yml启动

3.2 第二步：准备环境变量与主机地址

cd docker/astronAgent # 标准部署：复制环境变量模板 cp .env.example .env # 带鉴权部署：创建仅部署用户可读写的环境变量文件 install -m 600 .env.example .env

先配置应用入口地址（仅向用户公开 Nginx/Ingress，而不是内部各服务端口）：

HOST_BASE_ADDRESS=http://localhost

• 使用域名访问时，将localhost替换为你的域名
• 安全红线：内置 MinIO API 与管理控制台必须保持安全默认值——Docker Compose 仅绑定宿主机回环地址（127.0.0.1），Helm 使用ClusterIP。只有存在明确运维需求，并配置独立认证、TLS 与网络策略/防火墙限制时，才可显式开放相应端点；禁止将 MinIO 直接发布到互联网

3.3 第三步：配置 Casdoor 认证集成（带鉴权部署必选）

以带鉴权部署为例，.env中需要四个 Casdoor 关键配置项：

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

获取配置信息的完整流程（Casdoor 管理控制台http://localhost:8000，默认管理员admin / 123）：

1. 创建组织：进入/organizations页面，点击「添加」，填写组织名称后保存并退出
2. 创建应用并绑定组织：进入/applications页面，点击「添加」，填写：
   • Name：自定义应用名称，例如agent
   • Redirect URL：项目回调地址。Nginx 暴露端口为80时使用http://your-local-ip/callback；其他端口（如888）使用http://your-local-ip:888/callback
   • Organization：选择刚创建的组织名称
3. 信息对应关系：

4. 将上述信息填入.env后，如修改 Casdoor 应用，重启控制台服务生效：

docker compose restart console-frontend console-hub

从 Compose 源码看，docker-compose-auth.yml 中 Casdoor 镜像为casbin/casdoor:v2.67.0，以GIN_MODE=release生产模式运行，并依赖独立的casdoor-mysql（MySQL 8.4.6）保存认证数据；前端容器 docker-compose.yaml 的console-frontend与console-hub均通过CONSOLE_CASDOOR_URL/ID/APP/ORG四个环境变量接入认证体系，console-hub还通过OAUTH2_ISSUER_URI、OAUTH2_JWK_SET_URI、OAUTH2_AUDIENCE完成资源端的 JWT 校验。

3.4 第四步：启动 Astron Agent 核心服务

标准部署（不带 Casdoor）：

cd docker/astronAgent docker compose up -d

带鉴权部署（包含 Casdoor，推荐首次体验）：

cd docker/astronAgent # 变更服务前，先校验完整渲染后的凭据共享与健康检查契约 python3 scripts/verify_security_contract.py --compose-file docker-compose-with-auth.yaml # 启动所有服务，并等待已配置的健康检查收敛 docker compose -f docker-compose-with-auth.yaml up -d --wait --wait-timeout 900

带鉴权与 RPA 部署（包含 Casdoor 与 RPA 后端服务）：

cd docker/astronAgent python3 scripts/verify_security_contract.py --compose-file docker-compose-with-auth-rpa.yaml docker compose -f docker-compose-with-auth-rpa.yaml up -d

升级注意事项（来自带鉴权部署指南）：升级时必须让检出的 Compose 清单与应用镜像同步更新。docker compose pull只更新镜像，不会更新docker-compose.yaml；停止现有服务前应运行仓库提供的部署契约预检，并保留.env与命名卷。常规升级禁止使用down -v（会销毁命名卷中的数据）。

3.5 服务访问地址一览

四、核心服务拓扑：Compose 清单里的架构事实

从 docker-compose.yaml 可以梳理出标准部署的完整拓扑，这是理解后续配置项的依据：

• 基础设施层：postgres（PostgreSQL 14，库sparkdb_manager）、mysql（MySQL 8.4.6，库astron_console）、redis（Redis 7）、minio（对象存储，API/控制台端口18998/18999仅绑定127.0.0.1）。Elasticsearch、Kibana、Kafka、Logstash 在清单中以注释形式保留，可按需取消注释启用
• 核心服务层（ghcr.io/iflytek/astron-agent 镜像）：
  • core-tenant（5052）：租户服务，读取tenant_bootstrap_secrets卷中的租户凭据
  • core-database（7990）：记忆数据库服务，同时连接 PostgreSQL 与 MySQL
  • core-agent（17870）：Agent 服务，通过GET_WORKFLOWS_URL、CHUNK_QUERY_URL、LIST_MCP_PLUGIN_URL等环境变量编排对 workflow、knowledge、link 的调用
  • core-knowledge（20010）：知识库服务，自带/health/ready健康检查
  • core-workflow（7880）：工作流引擎，通过KNOWLEDGE_BASE_URL、PLUGIN_BASE_URL、AGENT_BASE_URL、APP_MANAGE_PLAT_BASE_URL等变量聚合各服务
  • core-link（18888）：外部工具/MCP 插件服务；core-aitools（18668）：AI 工具插件服务；core-rpa（17198）：RPA 插件服务
• 控制台层：console-hub（8080）承担后端聚合，console-frontend（1881）承担前端页面，nginx统一反向代理，对外暴露${EXPOSE_NGINX_PORT:-80}
• 一次性初始化任务：internal-credentials-init（busybox）在首次启动时自动生成并持久化工作流内部 API Key 与租户凭据；minio-credentials-check（busybox）校验对象存储凭据与OSS_REMOTE_ENDPOINT格式合法性，失败即退出并阻止 MinIO 启动

一个值得注意的安全设计：所有核心服务均通过depends_on ... condition: service_healthy等待基础设施健康检查通过后才启动，且各服务通过命名卷（workflow_internal_secrets、tenant_bootstrap_secrets、artifact_upload_secrets、sandbox_runtime_credential_secrets）共享内部凭据，而不是把密钥明文写进环境变量。

五、配置说明：.env关键变量速查

仓库的 配置说明 与 CONFIGURATION.md 将配置域归纳为四类：基础设施、模型与 AI 能力、平台能力、鉴权与安全。以下是.env中最常用变量的速查表（完整表格见 CONFIGURATION.md）：

独立部署中间件：如果中间件单独部署（不在同一 Docker 网络），需要将容器名（如postgres、mysql、redis、minio）替换为实际 IP 或域名，并同步修改对应连接信息（POSTGRES_HOST、MYSQL_HOST、REDIS_ADDR、OSS_ENDPOINT等）。

六、平台账号管理：业务能力的运行时配置

按部署文档的约定，业务能力账号不再写入.env。Astron Agent 启动并登录控制台后，在左侧菜单进入「平台账号管理」（与「应用管理」「资源管理」同级），包含四张配置卡片。保存配置后立即全局生效，系统自动刷新缓存，无需重启容器；如果某个功能依赖对应能力但尚未配置，系统会提示前往平台账号管理配置，不会阻塞系统启动。

1. 讯飞开放平台（内置星火模型、实时语音转写、图片生成等能力会使用）：PLATFORM_APP_ID、PLATFORM_API_KEY、PLATFORM_API_SECRET、SPARK_API_PASSWORD、SPARK_RTASR_API_KEY。注意：指令型助手的文本 AI 生成/优化需要开通 Spark Ultra 能力，工作流智能体的 AI 生成与 AI 代码生成需要开通 Spark3.5 Max 与 DeepSeekV3 能力
2. AI Ability Chat（平台 AI 生成相关能力，兼容 OpenAI 协议，用于提示词优化、一句话创建智能体等）：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。创建知识库时选择使用 RAGFlow 或星火知识库，只需配置实际使用的平台

RagFlow API Token 获取：访问http://localhost:18080，登录后点击头像进入用户设置，点击「API」生成 API KEY，填入RAGFLOW_API_TOKEN。

星火知识库数据集 ID 获取有两种方式：

• 方式一（页面获取）：使用讯飞开放平台创建的 APP_ID 和 API_SECRET，在页面中获取星火数据集 ID，详见 xinghuo_rag_tool.html
• 方式二（cURL 命令行创建数据集）：

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。

七、Helm / Kubernetes 生产化要点

当计划进入生产环境时，结合 helm/astron-agent 与 配置说明 一起评估。从 values.yaml 可以看到生产化部署的几个关键设计：

1. 版本与镜像管理：global.imageRegistry与global.astronAgentVersion统一控制镜像来源与版本，支持通过imagePullSecrets拉取私有镜像仓库
2. 密钥与凭据管理：
   • tenantBootstrap：租户身份由 Tenant、Console Hub、Agent、Workflow 共享，tenantId刻意保持稳定（680ab54f，因为已有数据引用它）；key/secret 与existingSecret.name留空时，Helm 在安装和在线升级时自动生成强随机 Secret 并通过lookup复用；离线 GitOps 渲染（helm template）无法查询集群中已存储的值，需引用预创建的 Secret
   • workflowInternalAuth：console-hub 调用 core-workflow 的共享认证，留空时由 Helm 生成并保留随机 Secret；checksum作为非敏感轮换标记
   • minio.auth.existingSecret：Chart 不渲染 MinIO 凭据，需预先创建；API 与控制台默认为相互独立的ClusterIPService，NodePort/LoadBalancer必须显式启用，开放 API 不会连带开放控制台
3. 资源与持久化：PostgreSQL（10Gi）、MySQL（10Gi）、Redis 均可独立配置persistence.size与resources.requests/limits，便于按集群容量规划
4. 网络策略：networkPolicy.enabled默认关闭，生产环境建议按需开启以收紧 Pod 间通信

八、推荐阅读与故障排查

按「由浅入深」顺序继续阅读：

1. 先读部署选型与入口：部署指南
2. 再读配置总览：配置说明 与 CONFIGURATION.md
3. 按部署形态选择：标准部署指南、带鉴权部署指南、带鉴权与 RPA 部署指南
4. 模块组成：模块说明
5. 遇到问题查看 FAQ 与 DEPLOYMENT_FAQ.md

排查建议：先查看相关服务的日志文件（各核心服务将日志目录挂载到docker/astronAgent/config/<module>/logs/），再检查官方文档与故障排除指南。首次部署建议在测试环境中验证所有功能后再部署到生产环境；常规升级务必保留.env与命名卷，禁止使用down -v。

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