Astron Agent：从本地部署到发布 HTTP/SSE 工作流的可复用流程

Astron Agent：从本地部署到发布 HTTP/SSE 工作流的可复用流程

这是什么？适合谁？

Astron Agent（星辰 Agent）是科大讯飞 iflytek 组织开源的企业级 Agentic Workflow 开发平台。 它把工作流编排、模型管理、AI/MCP 工具、RPA、知识库、团队协作与多租户能力放进一套自托管系统。 项目不是单一 Python 库，也不是只在网页里运行的提示词工具；它包含 React 控制台、Java 后端和多个 Python/Go 微服务。 公开集成边界是“已发布工作流的 HTTP/SSE API”，不是直接导入内部 Python/Java 模块。 适合谁：需要把模型、知识库、工具和 RPA 串成可管理流程，并希望自行部署的企业开发与平台团队。 适合场景：客服摘要、内部知识问答、审批辅助、跨系统自动化，以及需要流式输出的应用后端。 不适合谁：只想运行一个轻量脚本、没有 Docker/中间件运维能力，或不准备管理模型凭据与数据安全的人。 核验日期：2026-11-14。本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。

准备工作

准备一台测试机或隔离的测试环境，不要将默认 HTTP 服务直接暴露到公网。 核心 Agent 部署文档给出的最低参考是 2 Core CPU、4 GiB RAM、50 GB 磁盘。 若额外部署 RagFlow，文档参考提高到 4 Core CPU、16 GiB RAM、50 GB 磁盘；这不是所有场景的容量保证。 安装 Docker 与 Docker Compose，并确认本机 80、8000 端口未被其他服务占用；需要 RagFlow 时还包括 18080。 准备一个模型服务：官方支持通过 AI Ability Chat 的 OpenAI 协议地址、模型名与 API Key 接入，也可配置讯飞相关能力。 如需知识库，在 RagFlow 与星火知识库中选一种，不必为了“功能齐全”同时部署所有外部服务。 准备凭据管理方式：.env 只放基础设施配置，业务账号在启动后的“平台账号管理”页面填写。 先记录版本与部署清单；升级时 Compose 文件和应用镜像必须同步更新，不能只拉镜像而沿用旧清单。

第一步：准备部署目录与环境变量

克隆官方仓库并进入指定目录：

git clone https://github.com/iflytek/astron-agent.git
cd astron-agent/docker/astronAgent

部署文档推荐使用仅当前用户可读写的权限创建环境文件：

install -m 600 .env.example .env

在不支持 install 的平台上，可复制 .env.example 后自行限制文件权限。 编辑 .env，至少核对 HOST_BASE_ADDRESS 和 Casdoor 的 CONSOLE_CASDOOR_URL、CONSOLE_CASDOOR_ID、CONSOLE_CASDOOR_APP、CONSOLE_CASDOOR_ORG。 仅本地评估时使用文档的 localhost 配置；使用域名时同步修改主机地址和回调地址。 内部认证、Sandbox token 等字段留空时可由 Compose 首次启动自动生成并持久化，不要为了“填写完整”而随意覆盖。 MinIO API 与控制台默认只绑定回环地址；不要为远程方便直接发布到互联网。

第二步：启动并检查核心服务

变更服务前先运行仓库自带的安全契约校验：

python3 scripts/verify_security_contract.py --compose-file docker-compose-with-auth.yaml

通过后启动包含 Casdoor 的完整 Compose：

docker compose -f docker-compose-with-auth.yaml up -d --wait --wait-timeout 900

默认入口为 Astron Agent 前端 http://localhost/，Casdoor 管理界面 http://localhost:8000。 README 列出 Casdoor 初始管理员 admin / 123；登录后应立即按组织安全要求修改，不要把默认凭据用于共享或生产环境。 若启用 RagFlow，其入口为 http://localhost:18080，并需要单独配置 Chat 与 Embedding 默认模型。 首个部署成功判据：健康检查收敛，前端与认证页可访问，并能登录控制台；这不代表模型调用或工作流已经成功。

第三步：配置模型与业务账号

登录控制台，进入“平台账号管理”，而不是把业务 API Key 追加到公开文档或仓库。

AI Ability Chat 需要 AI_ABILITY_CHAT_BASE_URL、AI_ABILITY_CHAT_MODEL、AI_ABILITY_CHAT_API_KEY。 讯飞能力按所用功能配置 APP ID、API Key、API Secret、Spark API Password 或实时语音转写 Key。 知识库选择 RagFlow 时填写 Base URL、API Token、Timeout 与默认 Group；选择星火知识库时填写对应 Dataset ID。 保存后官方文档称配置全局生效并刷新缓存，不需要重启容器。 先用一个没有敏感数据的最小模型请求验证连通性，再进入工作流编排。

第四步：编排并调试最小可复用流程

本流程用“把支持请求整理成摘要”作为例子，不依赖虚构插件或私有接口。 在控制台创建并打开工作流编辑器，先定义 Start 节点的输入 query，类型为字符串。 只加入一个模型处理环节，要求输出三项：问题摘要、紧急程度、建议下一步。 定义 End 节点输出，确保应用方能得到稳定字段或文本；不要把内部节点细节当外部契约。 使用测试输入：用户无法登录，重置密码邮件没有收到，需要排查账号状态。 在编辑器中 Debug，检查模型是否返回摘要、输入是否正确传入、End 输出是否符合预期。 首个任务成功判据：同一测试输入可以多次完成，失败时能看到明确错误，且不依赖直接访问容器内部端口。 需要知识、MCP 或 RPA 时再逐项加入；每加一个节点就重跑同一测试，避免一次性引入多个故障源。

第五步：发布为应用 API

在编辑器选择 Publish，再选择 Publish as API。 创建或选择一个应用并完成发布，将 Service URL、Flow ID、API Key、API Secret 分开保存到服务端秘密存储。 Flow ID 是已发布流程的标识，不要误填 App ID 或编辑器内部 ID。 发布前固定 Start 输入和 End 输出；后续修改这两项就是修改调用方契约。 为测试与生产使用不同应用和凭据，便于独立轮换与撤销。

第六步：通过公开网关调用

官方公开端点为：

POST <ASTRON_BASE_URL>/workflow/v1/chat/completions

若控制台展示的 Service URL 不同，以发布时展示的地址为准。 认证头把应用 Key 与 Secret 用冒号连接：

Authorization: Bearer <application-key>:<application-secret>
Content-Type: application/json

最小请求体如下，parameters 的键必须与 Start 节点一致：

{
  "flow_id": "<FLOW_ID>",
  "uid": "user-123",
  "stream": true,
  "parameters": {
    "query": "Summarize this support request"
  }
}

flow_id 与 parameters 为必需；uid 最长 40 字符，chat_id 最长 128 字符。 继续会话时复用自己的 chat_id，不要把密码、令牌或敏感个人信息塞进 uid/chat_id。 不要调用 core-workflow:7880、/internal/gateway/auth/** 或容器 DNS 名称；这些不是稳定的外部集成边界。

第七步：处理 SSE、错误与中断

stream: true 时响应类型为 text/event-stream，每个 data: 帧包含 JSON。 追加 choices[0].delta.content 的非空内容，即使 HTTP 连接建立也要检查顶层 code。 code != 0 表示工作流错误；finish_reason: stop 表示正常完成；ping 帧是心跳，不是业务文本。 长节点运行时收到心跳但没有文本是可能现象，客户端仍应设置总体截止时间。 若收到 finish_reason: interrupt，保存 event_data.event_id，收集用户答复后调用：

POST <ASTRON_BASE_URL>/workflow/v1/resume

请求使用相同 Authorization，并提交 event_id、event_type: resume 与用户 content。 Event ID 是运行时状态，应及时恢复；过期或已经恢复的 event 要按错误处理，不要无限重放。 不需要逐 token 展示时可设 stream: false，解析同一顶层结构中的 code、message、choices 与 usage。

初级用法

客服摘要：固定输入 query，输出问题、紧急度和下一步，不直接执行账号修改。 内部知识问答：配置一种知识库，将检索与回答放入同一流程，发布前用无敏感样例测试。 内容分类：让模型输出有限类别，由应用后端做白名单校验，不直接把自由文本传入 RPA。 人工确认环节：对高风险操作使用 interrupt，把用户答复通过 resume 送回，而不是让 Agent 自行批准。

高级玩法

1. 把 RPA 放在模型决策之后 先由模型生成结构化建议，再由应用或流程校验，最后才调用 RPA 执行跨系统动作。 为每个外部动作设置权限、超时与审计记录，避免模型自由文本直接成为高风险指令。 2. 用 MCP 扩展工具但保持最小权限 只注册当前工作流需要的工具，分别测试参数校验、失败和超时。 MCP 可用不代表工具输出可信，外部内容仍应作为不可信输入处理。 3. 用 RagFlow 构建可替换知识层 先明确文档范围、Chat/Embedding 模型和默认组，再把知识节点接入流程。 将知识库凭据与业务应用凭据分离，便于单独轮换和撤销。 4. 用可观测性做受控排障 配置文档支持 OTLP 与 Langfuse；LANGFUSE_CAPTURE_INPUT_OUTPUT 默认关闭。 排障需要输入输出内容时先评估隐私与保留周期，不要为了日志完整而长期记录敏感提示词。

小技巧

1. 先把 Start/End 契约写下来，再拖节点；这比先堆功能更利于后续版本管理。
2. 每次只新增一个模型、知识库、MCP 或 RPA 节点，并用同一输入回归。
3. 业务 Key 放平台账号管理，基础设施变量放 .env，不要混用或提交到 Git。
4. 流式客户端按空行分帧并处理不完整缓冲，不要假设一次读取正好是一条事件。
5. 反向代理关闭响应缓冲并设置长读取超时，否则 SSE 可能变成一次性返回。
6. 记录响应 id、状态和耗时即可满足多数排障，凭据与敏感 prompt 必须脱敏。
7. 升级前保留 .env 与命名卷，禁止把 down -v 当常规升级命令。

踩坑记录

踩坑 1：Compose 启动后健康检查一直不收敛。 原因：中间件、端口、环境变量或镜像版本不匹配，不能仅凭容器存在判断成功。 排查：查看对应服务日志，重跑安全契约校验，确认 Compose 清单与镜像来自同一版本。 踩坑 2：控制台提示模型或知识库不可用。 原因：业务能力账号不是写在 .env 中，或选择的平台未配置。 排查：进入平台账号管理，核对 AI Ability Chat、讯飞或当前知识库的必填字段。 踩坑 3：API 返回 401 或凭据格式错误。 原因：Authorization 没有严格采用 Bearer <application-key>:<application-secret>，或值不属于发布时应用。 排查：检查空值、冒号与 Key/Secret 对应关系，在服务端安全地重新读取配置。 踩坑 4：提示找不到 Workflow 或无权访问。 原因：把 App ID、编辑器 ID 当成 Flow ID，或流程没有发布为 API。 排查：打开发布配置，复制该次发布展示的 Flow ID 与 Service URL。 踩坑 5：参数校验失败。 原因：parameters 的键或类型与 Start 节点不一致。 排查：以当前发布版本的 Start 节点为准，不凭旧文档猜字段。 踩坑 6：输出等很久后一次性到达。 原因：客户端不支持 SSE，或中间代理开启响应缓冲。 排查：确认 stream: true、Accept 与代理解析，逐层关闭缓冲并检查超时。 踩坑 7：interrupt 后无法继续。 原因：未保存 event_data.event_id、事件已过期，或重复恢复同一事件。 排查：从原帧读取 event_id，及时调用 resume，并把过期/已恢复作为需要重新运行的业务状态。

常见问题 FAQ

Q1：Astron Agent 是讯飞云服务的开源版本吗？

A：官方中文 README 称其核心技术与讯飞星辰 Agent 平台保持一致，并开源高可用版本。自托管版与云服务的账号、功能和计费不能默认等同，应以各自文档为准。

Q2：可以商用吗？

A：仓库与 LICENSE 为 Apache-2.0，官方明确允许使用、修改、分发与商业使用。实际项目仍需遵守第三方模型、工具、字体、数据和商标等独立条款。

Q3：是否必须部署 RagFlow？

A：不是。部署指南将 RagFlow 标为可选知识库组件；只有流程需要该知识库时才部署，也可按文档选择星火知识库。

Q4：是否必须调用 HTTP/SSE API？

A：只在把已发布流程接入其他应用时需要。单纯评估与操作平台可从控制台开始；贡献者研究内部模块不等于外部应用获得了稳定 SDK 契约。

Q5：能不能直接在浏览器里保存 API Secret 并调用？

A：不建议且不符合官方生产清单。Secret 应留在服务端秘密存储，浏览器或移动端先调用自己的后端，再由后端访问 Astron Agent。

Q6：Helm 是否可以直接用于生产？

A：文档站提供 Docker、Helm 与环境配置路径，但当前中文 README 仍有 Helm charts 完善中的提示。生产采用前应核对所检出版本的 Chart、文档与安全清单，不以旧示例命令代替验证。

Q7：开源是否意味着运行零成本？

A：不是。代码许可免费不等于模型 API、服务器、对象存储、知识库、RPA、可观测性服务和运维都免费。

权限、安全、成本与平台限制

生产入口只公开 Nginx/Ingress，Casdoor、MinIO、内部微服务和数据库不应任意暴露。 本地默认 HTTP 只适合可信测试环境；对外服务必须在 Nginx 或上游 Ingress 终止 TLS。

API Secret 不得进入浏览器代码、移动安装包、源码、截图或客户端日志。 对 parameters 做服务端校验，尤其是会进入工具、数据库或 RPA 的值。

Apache-2.0 降低代码商用限制，但不替代隐私保护、数据授权、内容审核和行业合规。 自托管成本包括计算、存储、网络、模型调用、知识库、RPA 与监控；官方未提供一个适用于所有部署的固定总价。 MagicNetWorld 未启动 Docker 栈、未配置模型、未运行工作流或调用 API，因此不声称已验证安装耗时、稳定性、输出质量与实际费用。

免责声明

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。 示例展示官方公开接口与可复用编排顺序，不是对任一版本的运行承诺；生产部署应先在隔离环境完整验证。

参考链接

• Astron Agent 官方项目页
• GitHub 仓库：iflytek/astron-agent
• 中文 README：功能、Docker Compose 与文档入口
• Quick Start
• HTTP/SSE 集成指南
• 认证部署指南
• 环境变量配置说明
• 项目模块说明
• Apache-2.0 License
• GitHub REST 仓库元数据