企业级AI Agent本地化部署实战：基于讯飞星辰与Astron的实战详解（附避坑清单）

文章目录1、讯飞星辰Agent开发平台与Astron介绍1.1 讯飞星辰Agent平台1.2 Astron1.3 Astron与星辰Agent对比2、硬件及环境建议2.1 硬件配置建议2.2 环境建议3、Astron部署3.1 拉取astron-agent到本地3.2 复制环境变量文件3.3 必要的环境变量配置3.4 讯飞开放平台秘钥获取3.5 启动Astron Agent3.6 访问Astron服务3.7 创建智能体4、部署失败常见问题说明是否支持docker-composefailed to copy: httpReadSeeker: failed opencasbin/casdoor镜像拉取失败服务启动成功访问后部分功能报错端口占用提示Spark API 错误或者调用量不足部署完成后打不开页面1、讯飞星辰Agent开发平台与Astron介绍如已了解Astron和星辰Agent可跳过前言看Astron安装部署内容1.1 讯飞星辰Agent平台讯飞星辰Agent平台是科大讯飞自研面向国内的企业级Agent开发平台。体验地址为https://agent.xfyun.cn/贯通功能开发-工程化落地-企业应用-数据闭环支持深度定制开发。1.2 AstronAstron 是科大讯飞推出的一款开源共建智能体平台。融合了 AI 工作流编排、模型管理、AI 与 MCP 工具集、RPA 自动化和团队空间等特性。企业级Agent平台、商用友好、支持高可用部署。可帮助企业快速构建可规模化落地的智能体应用打造面向未来的 AI 基座。1.3 Astron与星辰Agent对比博主个人理解 Astron 就是“开源版星辰 Agent”都是一个师傅教的破不了招啊。Astron面向开源社区星辰Agent面向商业交付。Astron开源讯飞星辰 Agent商业定位社区版智能体引擎降低门槛、吸引生态企业级平台规模化落地与商业交付代码 协议Apache 2.0 完全开源可商用、可二次开发核心同源但云端增值服务闭源功能完整性工作流、RPA、多模型、测评工具链全部给出不送 GPU/集群运维额外提供高可用集群、私有化知识库、托管 GPU、SLA 保障生态与工具内置 50 内置模型、870 AI 能力、1.6 万 MCP Server可插社区模型同库同能力且持续优先推送新模型、行业插件交互体验支持虚拟人、声音复刻、角色扮演可本地跑云端提供渲染资源开箱即用性能更高适用场景开发测试、POC、预算有限的中小企业、教育科研生产级大并发、数据敏感、需要官方运维与合规认证的大型政企2、硬件及环境建议博主本人是Windows系统使用了 Docker DesktopWSL2 环境来部署Astron。如果环境还未准备好可以参考博主的另一篇博客Docker Desktop WSL2 从安装配置到核心应用实战希望对你有点帮助。Docker Desktop 包括 Docker Compose、Docker Engine 和 Docker CLI组件对开发者使用Docker环境非常友好。2.1 硬件配置建议CPU 4CoreRAM 16GBDisk 50G2.2 环境建议Docker 26.1.4及以上Docker Compose 2.27.1及以上3、Astron部署AstronAgent 项目包含以下三个主要组件Casdoor、RagFlow、AstronAgentCasdoor身份认证和单点登录服务(必要部署组件,提供单点登录功能)RagFlow知识库和文档检索服务(非必要部署组件,根据需要部署)AstronAgent核心业务服务集群(必要部署组件)3.1 拉取astron-agent到本地通过git拉取项目到本地远程仓库地址git clone https://github.com/iflytek/astron-agent.git截止到2025/12/07的稳定版本是v1.0.0-rc.8此处将本地仓库切换到指定版本。# 克隆项目gitclone https://github.com/iflytek/astron-agent.git3.2 复制环境变量文件进入本地仓库的astron-agent项目根目录比如博主本地拉取到了E:\workspace\astron-agent路径下博主进入该路径后再进入到docker/astronAgent路径下复制环境变量配置文件编辑打开配置文件修改环境变量。如下是Linux命令。博主这里在Windows下直接打开复制后的.env文件进行修改。# 进入 astronAgent 目录cdastron-agent/docker/astronAgent# 复制环境变量配置cp.env.example .env# 环境变量配置vim.env3.3 必要的环境变量配置部分依赖讯飞开放平台的配置在下面讯飞开放平台秘钥获取中有说明。# 建议换成Astron稳定版本的镜像此处修改为v1.0.0-rc.8以github上实际版本为准 ASTRON_AGENT_VERSIONv1.0.0-rc.8 # 部署机器的IP地址博主这里本机部署使用localhost或127.0.0.1即可 HOST_BASE_ADDRESShttp://localhost # 讯飞开放平台应用ID、APIKey、APISecret PLATFORM_APP_ID39xx5a PLATFORM_API_KEYdcxx68 PLATFORM_API_SECRETY2xxIx # 星火模型的密钥 SPARK_API_PASSWORDIRxxxx3.4 讯飞开放平台秘钥获取登录讯飞开放平台进入控制台在我的应用下创建新应用。应用名称自定义即可此处博主已创建了名为AI 员工的应用点击应用进入能力配置页。打开左侧星火认知大模型选中Spark Ultra-32K大模型。右侧的http服务接口认证信息面板下包含了环境变量配置文件中的关键环境变量。http服务接口认证信息的鉴权信息APIPassword即环境变量中的SPARK_API_PASSWORDWebsocket服务接口认证信息的鉴权信息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额度3.5 启动Astron AgentWinR快捷键唤起运行窗口输入powershell回车打开Powershell命令行窗口切换到astron-agent本地仓库进入docker/astronAgent执行启动命令docker compose -f docker-compose-with-auth.yaml up -d回车即可首次启动会根据配置拉去镜像及其他依赖镜像。注意如果启动失败或者拉取镜像失败可以跳过直接看下面的部署失败常见问题说明希望对你有所帮助。顺利的话启动完成。如下图所示astron-agent镜像下的所有容器状态都是Healthy、Started。通过Docker Desktop也可以看到所有的容器都成功运行。3.6 访问Astron服务(1) Casdoor认证服务访问 Casdoor 管理控制台 http://localhost:8000初始化账号/密码admin/123(2) AstronAgent 核心服务控制台前端(nginx代理)http://localhost/此处使用admin登录即可。3.7 创建智能体此处以提示词驱动的智能体为例点击创建选择提示词创建。输入设定点击立即创建很快啊智能体就创建好了在调试预览面板可以试着让他讲一个冷笑话。回答的速度在4-6s还是可以的内容基本符合预期。4、部署失败常见问题说明当然了部署哪有那么顺利的呜呜呜博主第一次启动Astron镜像都没拉下来。是否支持docker-compose启动命令基于docker-compose博主使用的Docker Desktop已包含docker-compose如果是其他方式部署需要自己准备docker-compose环境。$:docker compose version $:Docker Compose version v2.40.3-desktop.1failed to copy: httpReadSeeker: failed openEOFEnd of File 表示连接在数据传输完成前被中断。 通常是由于网络不稳定、Docker Hub 被墙或镜像源不可用导致的。推荐使用国内镜像加速器来拉取镜像。比如阿里云、华为云、清华镜像、轩辕镜像等。此处以阿里云为例登录阿里云控制台找到容器镜像服务打开镜像工具下的镜像加速器查看自己的加速器地址。打开Docker Desktop设置的Docker Engine增加配置registry-mirrors。点击应用并重启Docker Desktop即可。{registry-mirrors:[https://6xxxf.mirror.aliyuncs.com]}casbin/casdoor镜像拉取失败casbin/casdoor确实不好拉取我这边开了代理然后在Docker Desktop尝试单独拉取casbin/casdoor试了3-5次成功拉取下来。或者找下国内镜像服务启动成功访问后部分功能报错检查环境变量是否是几个核心配置的值不正确。ASTRON_AGENT_VERSION是不是Astron的稳定版本。APP秘钥是否正确。ASTRON_AGENT_VERSIONv1.0.0-rc.8PLATFORM_APP_IDyour-app-idPLATFORM_API_KEYyour-api-keyPLATFORM_API_SECRETyour-api-secretSPARK_API_PASSWORDyour-api-password端口占用注意端口冲突问题Astron启用了很多端口可能会和你的其他服务冲突。提示Spark API 错误或者调用量不足需要检查下环境变量的Spark-API-Password是否正确。检查大模型token剩余量是否充足。部署完成后打不开页面以下命令慎重执行操作前做好备份。执行docker compose -f docker-compose-with-auth.yaml down -v清理容器和数据卷该步骤会删除所有数据。运行git restore docker清理docker目录下的改动将ASTRON_AGENT_VERSIONv1.0.0-rc.8设定为稳定版重新配置环境变量确保取值正确执行docker compose -f docker-compose-with-auth.yaml up -d重启服务清理浏览器换成使用无痕模式访问。Powered By niaonaoastron-agent 安装部署指南 https://scn5s6198j3j.feishu.cn/wiki/VefnwvPbridJBikCUb1cYXO9nYbastron-agent github https://github.com/iflytek/astron-agent/blob/main/README-zh.md/a