Shell / BashAI
讯飞星辰 Astron 智能体本地化部署实战指南
介绍讯飞星辰 Astron 智能体的本地化部署流程。涵盖硬件环境建议、Docker 及 WSL2 配置、环境变量设置、密钥获取及服务启动步骤。包含常见问题排查，如镜像拉取失败、端口占用及 API 调用错误等解决方案，旨在帮助用户快速搭建企业级 AI Agent 基座。
介绍讯飞星辰 Astron 智能体的本地化部署流程。涵盖硬件环境建议、Docker 及 WSL2 配置、环境变量设置、密钥获取及服务启动步骤。包含常见问题排查，如镜像拉取失败、端口占用及 API 调用错误等解决方案，旨在帮助用户快速搭建企业级 AI Agent 基座。
讯飞星辰 Agent 平台是科大讯飞自研的企业级 Agent 开发平台。体验地址为 https://agent.xfyun.cn/
贯通功能开发 - 工程化落地 - 企业应用 - 数据闭环，支持深度定制开发。
Astron 是科大讯飞推出的一款开源共建智能体平台。
融合了 AI 工作流编排、模型管理、AI 与 MCP 工具集、RPA 自动化和团队空间等特性。
企业级 Agent 平台、商用友好、支持高可用部署。可帮助企业快速构建可规模化落地的智能体应用，打造面向未来的 AI 基座。
Astron 面向开源社区，星辰 Agent 面向商业交付。
| Astron（开源） | 讯飞星辰 Agent（商业） | |
|---|---|---|
| 定位 | 社区版智能体引擎，降低门槛、吸引生态 | 企业级平台，规模化落地与商业交付 |
| 代码 & 协议 | Apache 2.0 完全开源，可商用、可二次开发 | 核心同源，但云端增值服务闭源 |
| 功能完整性 | 工作流、RPA、多模型、测评工具链全部给出；不送 GPU/集群运维 | 额外提供高可用集群、私有化知识库、托管 GPU、SLA 保障 |
| 生态与工具 | 内置 50+ 内置模型、870+ AI 能力、1.6 万 MCP Server，可插社区模型 | 同库同能力，且持续优先推送新模型、行业插件 |
| 交互体验 | 支持虚拟人、声音复刻、角色扮演，可本地跑 | 云端提供渲染资源，开箱即用，性能更高 |
| 适用场景 | 开发测试、POC、预算有限的中小企业、教育科研 | 生产级大并发、数据敏感、需要官方运维与合规认证的大型政企 |
本文基于 Windows 系统，使用 Docker Desktop+WSL2 环境来部署 Astron。
Docker Desktop 包括 Docker Compose、Docker Engine 和 Docker CLI 组件，对开发者使用 Docker 环境非常友好。
AstronAgent 项目包含以下三个主要组件 Casdoor、RagFlow、AstronAgent：
通过 git 拉取项目到本地，远程仓库地址 git clone https://github.com/iflytek/astron-agent.git
截止到 2025/12/07 的稳定版本是 v1.0.0-rc.8，此处将本地仓库切换到指定版本。
# 克隆项目
git clone https://github.com/iflytek/astron-agent.git
进入本地仓库的 astron-agent 项目根目录，例如 E:\workspace\astron-agent 路径下，再进入到 docker/astronAgent 路径下，复制环境变量配置文件，编辑打开配置文件，修改环境变量。
如下是 Linux 命令。在 Windows 下可直接打开复制后的.env 文件进行修改。
# 进入 astronAgent 目录
cd astron-agent/docker/astronAgent
# 复制环境变量配置
cp .env.example .env
# 环境变量配置
vim .env
部分依赖讯飞开放平台的配置，在下面'讯飞开放平台秘钥获取'中有说明。
# 建议换成 Astron 稳定版本的镜像，此处修改为 v1.0.0-rc.8，以 github 上实际版本为准
ASTRON_AGENT_VERSION=v1.0.0-rc.8
# 部署机器的 IP 地址，本机部署，使用 localhost 或 127.0.0.1 即可
HOST_BASE_ADDRESS=http://localhost
# 讯飞开放平台应用 ID、APIKey、APISecret
PLATFORM_APP_ID=39xx5a
PLATFORM_API_KEY=dcxx68
PLATFORM_API_SECRET=Y2xxIx
# 星火模型的密钥
SPARK_API_PASSWORD=IRxxxx
登录 讯飞开放平台，进入控制台，在我的应用下创建新应用。
应用名称自定义即可，点击应用进入能力配置页。
打开左侧星火认知大模型，选中 Spark Ultra-32K 大模型。
右侧的 http 服务接口认证信息面板下包含了环境变量配置文件中的关键环境变量。
http 服务接口认证信息的鉴权信息 APIPassword 即环境变量中的 SPARK_API_PASSWORD
Websocket 服务接口认证信息的鉴权信息 APPID、APISecret、APIKey 即环境变量中 PLATFORM_APP_ID、PLATFORM_API_KEY、PLATFORM_API_SECRET
修改 ./docker/astronAgent/.env 环境变量配置后保存即可。
注意：讯飞的 APISecret 和 APIKey 的顺序，不要配错顺序哈。
可以点击立即领取，有免费的 token 试用额度。确保自己在讯飞开放平台 Spark Ultra-32K 大模型有一定的 token 余量，避免 Astron 部署完成后，无法创建智能体。
注意：可以领取下 Spark Ultra-32K 的 token 额度
Win+R 快捷键唤起运行窗口，输入 powershell 回车打开 Powershell 命令行窗口，切换到 astron-agent 本地仓库，进入 docker/astronAgent，执行启动命令 docker compose -f docker-compose-with-auth.yaml up -d，回车即可。
首次启动会根据配置拉去镜像及其他依赖镜像。
注意：如果启动失败或者拉取镜像失败可以跳过，直接看下面的'部署失败常见问题说明'。
顺利的话，启动完成。
如下图所示，astron-agent 镜像下的所有容器状态都是 Healthy、Started。
通过 Docker Desktop 也可以看到所有的容器都成功运行。
(1) Casdoor 认证服务
访问 Casdoor 管理控制台：http://localhost:8000，初始化账号/密码：admin/123
(2) AstronAgent 核心服务
控制台前端 (nginx 代理)：http://localhost/，此处使用 admin 登录即可。
此处以提示词驱动的智能体为例。
点击创建，选择提示词创建。输入设定，点击立即创建。
很快，智能体就创建好了，在调试预览面板，可以试着让他讲一个冷笑话。
回答的速度在 4-6s 还是可以的，内容基本符合预期。
启动命令基于 docker-compose，使用的 Docker Desktop 已包含 docker-compose，如果是其他方式部署，需要自己准备 docker-compose 环境。
$:docker compose version
$:Docker Compose version v2.40.3-desktop.1
EOF（End of File）表示连接在数据传输完成前被中断。通常是由于网络不稳定、Docker Hub 被墙或镜像源不可用导致的。
推荐使用国内镜像加速器，来拉取镜像。比如阿里云、华为云、清华镜像、轩辕镜像等。
此处以阿里云为例，登录阿里云控制台，找到容器镜像服务，打开镜像工具下的镜像加速器查看自己的加速器地址。
打开 Docker Desktop 设置的 Docker Engine，增加配置 registry-mirrors。点击应用并重启 Docker Desktop 即可。
{"registry-mirrors":["https://6xxxf.mirror.aliyuncs.com"]}
casbin/casdoor 确实不好拉取，开了代理然后在 Docker Desktop 尝试单独拉取 casbin/casdoor，试了 3-5 次成功拉取下来。
或者找下国内镜像。
检查环境变量是否是几个核心配置的值不正确。
ASTRON_AGENT_VERSION 是不是 Astron 的稳定版本。
APP 秘钥是否正确。
ASTRON_AGENT_VERSION=v1.0.0-rc.8
PLATFORM_APP_ID=your-app-id
PLATFORM_API_KEY=your-api-key
PLATFORM_API_SECRET=your-api-secret
SPARK_API_PASSWORD=your-api-password
注意端口冲突问题，Astron 启用了很多端口，可能会和你的其他服务冲突。
需要检查下环境变量的 Spark-API-Password 是否正确。
检查大模型 token 剩余量是否充足。
以下命令慎重执行，操作前做好备份。
执行 docker compose -f docker-compose-with-auth.yaml down -v 清理容器和数据卷，该步骤会删除所有数据。
运行 git restore docker 清理 docker 目录下的改动
将 ASTRON_AGENT_VERSION=v1.0.0-rc.8 设定为稳定版
重新配置环境变量，确保取值正确
执行 docker compose -f docker-compose-with-auth.yaml up -d 重启服务
清理浏览器缓存，使用无痕模式访问。
astron-agent github README
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online