ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Astron Agent 安装与启动 FAQ 实战指南:镜像加速、端口冲突、数据持久化与版本管理的完整排障手册

Astron Agent 安装与启动 FAQ 实战指南:镜像加速、端口冲突、数据持久化与版本管理的完整排障手册 人工智能AI AgentAgent 编排RPA后端前端企业应用【免费下载链接】astron-agentEnterprise-grade, commercial-friendly agentic workflow platform for building next-generation SuperAgents.项目地址https://gitcode.com/gh_mirrors/as/astron-agent点击查看免费下载本指南围绕 Astron Agent企业级、商业友好的智能体工作流平台的容器化部署场景系统讲解从镜像拉取、服务启动到日常升级维护全过程中的高频问题与解决方案。读者按照本文操作后可以独立完成镜像加速配置、端口冲突排查、HTTP 5xx 排障、Casdoor 数据持久化修复以及镜像版本锁定等部署运维任务让基于 Docker Compose 的 Astron Agent 集群稳定跑起来。前置认知为什么 Astron Agent 必须依赖 DockerAstron Agent 平台的所有组件身份认证、知识库、核心业务服务、控制台前端与后端都以容器形式交付因此 Docker 与 Docker Compose 是硬性前置条件不存在免容器化的部署路径。从部署架构看项目包含三类组件详见 部署指南Casdoor开源的认证与单点登录服务承载平台登录体系RAGFlow可选部署的知识库与文档检索服务astronAgent 核心服务集群包括 Nginx 反向代理、console-frontend控制台前端、console-hubJava 管理后端以及core-tenant、core-workflow、core-agent、core-knowledge、core-link、core-rpa、core-aitools、core-database等 Python/Go 核心服务外加 MySQL、PostgreSQL、Redis、MinIO 等基础设施。所有这些服务统一定义在 docker-compose.yaml 中由单个docker compose up拉起。因此部署前请先确认 Docker 与 Docker Compose 已正确安装并保证服务器可以访问外部网络以拉取镜像。镜像拉取失败Download failed或速度慢镜像拉取失败通常由国内网络连接 Docker Hub / GitHub Container Registry 不稳定导致可以按以下三个层面依次解决。1. 配置国内镜像加速源在 Docker 守护进程配置文件/etc/docker/daemon.json中写入国内加速镜像地址如阿里云、网易、南京大学等提供的加速服务然后重启 Docker 使配置生效{ registry-mirrors: [https://docker.mirrors.ustc.edu.cn] }需要注意Astron Agent 的核心镜像托管在ghcr.ioGitHub Container Registry而一般镜像加速源只覆盖 Docker Hub。对于ghcr.io可以使用其国内替代地址例如ghcr.nju.edu.cn可作为ghcr.io的镜像。2. 替换 Compose 文件中的镜像地址编辑 docker-compose.yaml把镜像字段中ghcr.io/前缀替换为可用的国内镜像源地址。以核心服务为例镜像字段形如core-tenant: image: ghcr.io/iflytek/astron-agent/core-tenant:${ASTRON_AGENT_VERSION:-latest}将其中的ghcr.io/替换为ghcr.nju.edu.cn/即可。从源码结构看docker-compose.yaml中所有核心服务console-frontend、console-hub、core-*系列均采用这一镜像命名模式因此替换时需要逐个服务核对保持一致。3. 配置网络代理如果服务器位于受限网络环境确保可以访问外部网络或为 Docker 配置 HTTP/HTTPS 代理通过 Docker 客户端的HTTP_PROXY/HTTPS_PROXY环境变量或 daemon 配置。启动时提示端口被占用Port occupiedAstron Agent 默认暴露以下主机端口可以从 docker-compose.yaml 与 docker-compose-auth.yml 中确认端口用途Compose 中的可配置项80Nginx 反向代理平台入口EXPOSE_NGINX_PORT默认 808000Casdoor 认证服务CASDOOR_PORT默认 800018998MinIO 对象存储 APIEXPOSE_MINIO_PORT默认 1899818999MinIO 管理控制台EXPOSE_MINIO_CONSOLE_PORT默认 18999排查与解决步骤确认冲突端口用ss -tlnp或lsof -i :端口查看本机端口占用情况确认是否被其他进程或旧的容器占用修改映射在项目根目录的.env文件中修改冲突服务的端口映射变量例如EXPOSE_NGINX_PORT888、CASDOOR_PORT8001清理旧容器确保没有旧的容器实例仍在运行先执行docker compose down清理后再重新启动。部署后访问 404 或 502 Bad Gateway启动完成后访问平台页面出现 404 或 502通常属于以下三类原因查看日志定位执行docker compose logs -f实时查看astron-agent-console-hub或nginx容器的报错信息重点观察是否有连接被拒、服务未就绪等记录耐心等待初始化服务启动需要时间尤其是第一次部署时需要拉取全部镜像、初始化 MySQL/PostgreSQL 数据库并执行建表脚本。可以从 docker-compose.yaml 看到所有服务都通过healthcheck做了健康检查如curl -f http://localhost/nginx-health、mysqladmin ping健康检查通过前依赖方不会真正对外服务因此请以健康检查通过而非容器已启动作为就绪标准检查HOST_BASE_ADDRESS确认.env中的HOST_BASE_ADDRESS配置正确。远程部署时应为公网 IP 或域名而不能是localhost。该变量会传入 Casdoor 容器见 docker-compose-auth.yml 中的HOST_BASE_ADDRESS${HOST_BASE_ADDRESS:-http://localhost}用于生成正确的回调地址配置错误会直接导致登录跳转与接口访问异常。如何更新到最新版本标准升级流程如下# 1. 拉取最新代码 git pull origin main # 2. 拉取最新镜像 docker compose pull # 3. 重启服务 docker compose down docker compose up -d注意事项如果新版本涉及数据库字段变更可能需要执行数据库迁移测试环境允许的情况下可以使用docker compose down -v清空数据卷重新初始化——该命令会删除所有数据生产环境务必慎用。Windows 上运行对 Docker Desktop 版本有要求吗建议使用Docker Desktop 4.x 及以上版本最好使用最新的稳定版以避免 API 版本不匹配等兼容性问题。Windows 用户在升级 Docker Desktop 后如果遇到容器无法启动通常是 WSL 2 后端或 API 版本不同步所致重启 Docker Desktop 即可恢复。启动时遇到 request returned 500 Internal Server Error该报错通常是环境状态不一致例如残留的旧数据卷、被修改过的配置文件与当前镜像版本不匹配导致的按以下顺序清理并重建# 1. 备份重要数据数据卷、数据库、.env 等 # 2. 清理容器与数据卷注意会删除数据 docker compose -f docker-compose-with-auth.yaml down -v # 3. 还原 docker 目录下被修改的文件 git restore docker # 4. 检查 ASTRON_AGENT_VERSION 是否设置为稳定版如 v1.0.0-rc.x # 避免使用未经验证的中间版本 # 5. 重新启动 docker compose -f docker-compose-with-auth.yaml up -d # 6. 清理浏览器缓存或使用无痕模式重新访问其中第 2 步使用的 docker-compose-with-auth.yaml 通过 Compose 的include机制组合了 Casdoor 认证服务与核心服务是带认证部署的标准入口。第 4 步的ASTRON_AGENT_VERSION会注入到所有核心镜像的 tag 中如image: ghcr.io/iflytek/astron-agent/core-tenant:${ASTRON_AGENT_VERSION:-latest}版本混乱是 500 错误的常见诱因。如何正确修改默认端口80平台默认通过 Nginx 暴露在 80 端口修改方式如下在.env文件中修改EXPOSE_NGINX_PORT等相关端口配置重建容器使配置生效docker compose down后再docker compose up -d。从 docker-compose.yaml 可以看到Nginx 服务的端口映射为${EXPOSE_NGINX_PORT:-80}:80修改该变量后必须重建容器仅重启不会重新应用端口映射。重要提醒如果同时启用了 Casdoor 认证修改端口后还需要同步更新 Casdoor 应用的回调地址否则登录会因为redirect_uri不匹配而失败。具体地在 Casdoor 管理控制台的应用配置中将 Redirect URL 从http://your-local-ip/callback改为http://your-local-ip:新端口/callback。相关细节参见 配置与认证 FAQ。为什么用了 latest 镜像却不是最新的如何切换镜像版本Docker 的latest标签有一个常见行为只在本地没有该镜像时才会真正去拉取之后会一直复用本地缓存的旧镜像因此代码更新了但跑的还是旧版本。对应解决方式想更新到最新必须显式执行docker compose pull强制拉取新镜像再docker compose up -d重建容器想锁定版本在.env中把ASTRON_AGENT_VERSION从latest改成具体版本号如v1.0.0Compose 中的image: ...:${ASTRON_AGENT_VERSION:-latest}会随之指向固定 tag。生产环境推荐锁定具体版本号而不是使用latest这样环境可控、可回滚避免意外升级引入不兼容变更。支持在 ARM 架构的机器上部署吗支持。docker compose up会读取 docker-compose.yaml 中各服务的image字段并执行docker pullDocker 引擎会根据当前运行环境自动选择匹配的架构版本在 ARM Mac 上拉取 arm64 镜像在 x86 服务器上拉取 amd64 镜像。只要对应镜像在仓库中发布了多架构multi-arch清单即可直接运行无需人工干预。项目重启后用户数据丢失项目的身份认证系统采用开源框架 Casdoor如果重启后出现用户数据丢失例如用户 ID 变化、账号关联数据失效请检查 Casdoor 的配置文件 docker/astronAgent/casdoor/conf/app.conf 中的initDataNewOnly该值必须为true当前仓库中的默认配置即为initDataNewOnly true如果被改为falseCasdoor 每次重启都会重新执行初始化数据用户 ID 会发生变化从而导致关联的用户数据如智能体、工作流归属丢失。从仓库配置看app.conf 同时配合initDataFile /conf/init_data.json完成首次初始化恢复该配置后重新启动即可保持用户数据的稳定性。打开 RPA 客户端卡在加载界面RPA机器人流程自动化客户端连接不上服务端时会长时间停留在加载界面按以下顺序排查检查 RPA 服务端确认各组件是否正常启动、有无异常退出查看core-rpa及相关服务的日志检查客户端配置打开 RPA 客户端安装目录下resources目录中的 conf 配置文件确认remote_addr指向的 RPA 服务端 nginx 地址和端口填写正确端口默认为 32742并确保该地址端口从客户端所在机器可以正常访问。上图展示了客户端 conf 配置文件中remote_addr的典型填法将地址指向 RPA 服务端 nginx 的 IP 与端口默认 32742保存后重新启动客户端即可。若仍无法加载再回到服务端检查 nginx 与 RPA 后端是否监听正常。Astron RPA 客户端支持国产信创或麒麟系统吗开源版暂不支持该能力仅企业版提供。开源版 RPA 客户端目前只支持 Windows操作系统如需在国产信创或麒麟系统上使用 RPA 能力需要评估企业版方案。排障速查表症状最快定位方式关键配置/文件镜像拉取失败检查网络与镜像源/etc/docker/daemon.json、docker-compose.yaml中的 image 字段端口被占用ss -tlnp查看占用.env中的EXPOSE_NGINX_PORT、CASDOOR_PORT、EXPOSE_MINIO_PORT404 / 502docker compose logs -f.env中的HOST_BASE_ADDRESS500 Internal Server Error清理数据卷并重建ASTRON_AGENT_VERSION、docker-compose-with-auth.yamllatest 不是最新检查本地镜像缓存docker compose pull、.env中的ASTRON_AGENT_VERSION重启后用户数据丢失检查 Casdoor 配置casdoor/conf/app.conf 中的initDataNewOnlyRPA 客户端卡加载检查服务端与客户端 conf客户端resources目录 conf 中的remote_addr默认 32742掌握以上问题的成因与处理路径即可覆盖 Astron Agent 容器化部署中最常见的启动与运维故障。对于未覆盖到的异常优先结合docker compose logs与各服务健康检查状态定位更多部署细节可参阅 完整部署指南。赞分享人工智能AI AgentAgent 编排RPA后端前端企业应用【免费下载链接】astron-agentEnterprise-grade, commercial-friendly agentic workflow platform for building next-generation SuperAgents.项目地址https://gitcode.com/gh_mirrors/as/astron-agent点击查看免费下载相关推荐Astron Agent 部署 FAQ 实战指南升级、启动故障排查与镜像加速方案Astron Agent 部署 FAQ 实战指南升级、启动故障排查与镜像加速方案 本文基于 Astron Agent 仓库的 docs/DEPLOYMENT_人工智能AI AgentAgent 编排RPA后端前端企业应用Docker镜像性能优化60%实战PDFMathTranslate启动加速与中文排版完整方案Docker镜像性能优化60%实战PDFMathTranslate启动加速与中文排版完整方案 PDFMathTranslate作为一款基于AI的PDF文档全文AI 应用NLPCLIKubescape 故障排查指南从安装、扫描到镜像漏洞修复的完整排障手册Kubescape 故障排查指南从安装、扫描到镜像漏洞修复的完整排障手册 导读 Kubescape 是一款开源的 Kubernetes 安全平台覆盖 IDE网络安全云原生应用安全运维上一篇从零开始构建个人音频收藏系统打造专属有声资源管理方案下一篇Mac菜单栏管理效率工具三步优化你的工作流创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表