最近我在内网服务器上把讯飞 Astron Agent 掘金版完整跑了一遍整个过程靠一套 Docker Compose 编排文件搞定。这套东西说白了就是一套可私有化部署的 Agent 开发与运行平台部署完之后创建智能体、编排工作流、传文档建知识库、接大模型接口这些操作全都可以在自己服务器上完成数据不出内网心里踏实。这类平台私有化部署最难的不是命令多而是搞不清楚服务之间怎么协作、数据存在哪、模型从哪接。我这次踩了几个坑之后把整个流程理顺了。这篇文章就按我实际部署的顺序来写把每一步为什么这么做讲清楚最后整理了一份常见问题排查记录。如果你正准备在自己的机器上装一套讯飞 Astron Agent 掘金版或者对 Agent 平台私有化部署感兴趣这篇文章应该能帮你省下不少折腾的时间。1. 项目概述与部署思路1.1 这套系统到底是什么、掘金版能干什么先说清楚 Astron Agent 是干嘛的。你可以把它理解成一个“智能体开发中台”管理员在网页控制台里创建 Agent给它配置人设和工具上传企业内部文档做成知识库把工作流编排成自动执行的任务最后通过对话窗口或者 API 接口把能力开放给业务系统调用。整个过程不需要从零写前端和后端平台已经把基础设施搭好了。掘金版是社区/开发者体验方向的版本跟企业商用版相比功能上做了一些裁剪但核心链路是完整可用的。我实际用下来Agent 编排、知识库问答、插件调用、对话日志管理这些常用功能都在。对于团队内部做技术验证、搭建业务原型、跑通 Agent 应用场景来说这个版本足够用了而且免费这一点对预算敏感的小团队非常友好。部署到内网之后它解决的核心问题就是数据安全和企业知识资产复用。公司内部的制度文档、产品手册、售后话术以前散落在各个地方现在可以统一上传到知识库系统自动完成文本解析、切片和向量化员工提问时直接从库里检索相关内容再由大模型组织答案。对一些不想把内部资料传到公网服务的团队来说这种私有化部署方式是刚需。1.2 为什么选 Docker Compose 而不是源码编译或 Kubernetes我最初也考虑过源码编译部署毕竟“官方文档优先”是很多人的第一反应。但实际评估下来源码编译要处理 Node 环境、Python 环境、系统依赖库、编译工具链等一系列问题光环境准备就得折腾大半天中间任何一个依赖版本对不上排查成本都很高。Kubernetes 我也排除了原因很简单整套系统用在单机或者双机场景用 K8s 属于杀鸡用牛刀。K8s 确实功能强大但引入了 etcd、网络插件、Ingress Controller 等一堆额外组件对部署和运维能力的要求远高于这套系统本身的需求。对于大多数中小团队来说一台 4核16G 的服务器就能跑得很稳没必要为了“高大上”给自己增加维护负担。Docker Compose 正好卡在中间用一份 YAML 文件把数据库、缓存、后端服务、前端页面的启动参数、端口、数据卷、依赖关系全部声明清楚。执行 docker compose up -d 一条命令就把整套系统拉起来组件之间的网络通信由 Docker 内部网络解决不会跟宿主机现有环境冲突。后续升级、回滚、迁移也都很直观性价比最高。一句话总结单机或少量机器场景Compose 就是最优解。1.3 整体架构与容器服务划分在写编排文件之前先要理解这套系统由哪些组件组成。我部署时把服务划分为以下几个角色服务名职责技术选型web前端控制台负责页面展示和用户交互Nginx 静态资源server后端 API 服务负责业务逻辑和 Agent 编排调度主业务服务worker异步任务执行、工具调用、定时任务独立工作进程postgres业务数据存储保存账号、Agent 配置、知识库元数据PostgreSQLredis缓存、会话管理与任务队列Redis这套划分结构很典型PostgreSQL 作为唯一的数据主库Redis 承担缓存和队列职责server 处理同步请求worker 处理异步任务。前端页面由 Nginx 托管通过反向代理把 API 请求转发到 server 容器。理解了这个结构后面配置环境变量、排查问题就有了清晰的方向。2. 环境准备与前置规划2.1 硬件配置与系统要求先说硬件。Astron Agent 本身对计算资源的消耗并不算极端但大模型推理和向量检索都吃内存。我实际部署时的服务器配置是 4核 CPU、16G 内存、100G SSD跑完整套系统后观察内存占用在 8G 到 12G 之间波动磁盘占用约 20G包含镜像和初始数据。如果你是纯测试环境2核4G 也能把服务拉起来但一旦开始上传文档、做知识库问答内存瓶颈会很快显现建议至少 4核8G 起步。生产环境直接按 4核16G 以上规划。操作系统方面我使用的是 Ubuntu 22.04 LTS这也是最省心的选择。CentOS 7 的默认内核和 Docker 兼容性略差需要额外处理一些依赖Debian 系整体都还好。如果你用 CentOS建议至少升级到 7.9 并安装较新版本的 Docker。另外文件系统建议用 ext4 或 xfs避免特殊文件系统导致的权限问题。2.2 安装 Docker 与 Compose 插件我这次用的是 Docker 的 Compose 插件docker compose 命令不是老版的 docker-compose 独立二进制。新版插件是官方推荐方式语法和兼容性都更可靠。安装步骤以 Ubuntu 22.04 为例# 安装必要依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG 密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 添加 Docker 软件源 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker 和 Compose 插件 sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin装完之后验证一下版本docker --version docker compose version这里有个注意事项如果你只是执行了 apt install docker.ioUbuntu 自带源里的旧版本 Docker那大概率没有 Compose 插件需要单独处理。我建议直接按上面的官方源方式安装一步到位。装好之后把当前用户加入 docker 组这样不用每条命令都加 sudosudo usermod -aG docker $USER改完用户组之后记得重新登录或者执行 newgrp docker 让配置生效。2.3 目录规划与镜像获取策略部署之前先规划好目录结构。我习惯把整套系统放在一个独立的项目目录下这样后续备份、升级、迁移都方便。我这边实际使用的结构是这样/opt/astron/ ├── docker-compose.yml ├── .env ├── data/ │ ├── postgres/ # PostgreSQL 数据文件 │ ├── redis/ # Redis 持久化数据 │ └── storage/ # 平台上传的附件、知识库文件 └── logs/ # 容器日志数据目录单独拎出来的原因后面会详细讲这里先记住结论凡是需要长期保存的数据都必须映射到宿主机目录不能放在容器内部。镜像获取这块如果你的服务器能直接访问 Docker Hub那就下载官方镜像拉取就行。如果部署环境是内网隔离的可以在一台有外网的机器上先把镜像拉下来并导出压缩包docker pull 镜像地址:版本 docker save 镜像地址:版本 | gzip astron-images.tar.gz再把压缩包拷贝到内网服务器上导入docker load astron-images.tar.gz镜像版本建议锁定具体的版本号不要用 latest 标签。原因是 latest 会随官方发布更新下次部署或重启时可能拉到不兼容的新版本导致整套系统行为变化。锁定版本号之后配合 docker-compose.yml 的配置整个环境是确定性的出问题也好排查。3. 编排文件与核心配置3.1 docker-compose.yml 逐项拆解核心文件就是 docker-compose.yml。下面这份是我实际使用时的精简版本服务名以官方发布为准但结构可以复用services: postgres: image: postgres:16 container_name: astron-postgres restart: always environment: POSTGRES_USER: astron POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_DB: astron volumes: - ./data/postgres:/var/lib/postgresql/data networks: - astron-net healthcheck: test: [CMD-SHELL, pg_isready -U astron -d astron] interval: 10s timeout: 5s retries: 5 redis: image: redis:7-alpine container_name: astron-redis restart: always command: [redis-server, --appendonly, yes] volumes: - ./data/redis:/data networks: - astron-net healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 server: image: astron-agent-server:版本号 container_name: astron-server restart: always depends_on: postgres: condition: service_healthy redis: condition: service_healthy environment: DB_HOST: postgres DB_PORT: 5432 DB_USER: astron DB_PASSWORD: ${DB_PASSWORD} DB_NAME: astron REDIS_HOST: redis REDIS_PORT: 6379 MODEL_API_KEY: ${MODEL_API_KEY} MODEL_API_BASE: ${MODEL_API_BASE} APP_SECRET: ${APP_SECRET} volumes: - ./data/storage:/app/storage networks: - astron-net ports: - 8080:8080 web: image: astron-agent-web:版本号 container_name: astron-web restart: always depends_on: - server ports: - 80:80 networks: - astron-net volumes: - ./logs/nginx:/var/log/nginx这份文件里有几个细节值得展开说。第一postgres 和 redis 都配了 healthcheck而 server 的 depends_on 用了 condition: service_healthy。很多人部署容器服务时只写 depends_on: - postgres这只能保证 postgres 容器启动了但不能保证数据库已经可以接受连接。如果不加健康检查server 启动时数据库可能还没就绪就会报连接失败然后退出。用 condition: service_healthy 可以确保数据库真正 ready 后再启动 server这是避免启动顺序问题的关键手段。第二redis 启动命令加上了 --appendonly yes这是开启 AOF 持久化。如果不加这个参数Redis 重启后缓存数据会全部丢失。虽然缓存数据丢了影响没有数据库大但会话信息和任务队列丢失会导致用户重新登录、异步任务异常最好还是开启持久化。第三server 的 8080 端口和 web 的 80 端口暴露到宿主机。如果你宿主机上已经有 Nginx 或其他 Web 服务占用了 80 端口可以把 web 的端口映射改成其他值例如 8081:80后面访问时用带端口的地址。第四restart: always 的作用是容器异常退出时自动重启。这个配置在实际运维中非常重要宿主机重启后 Docker 会自动把整套服务拉起来不用人工介入。3.2 环境变量与模型接口配置上一份文件里用到了几个环境变量这些变量的值放在项目目录的 .env 文件里。Compose 会自动读取同名 .env 文件填充变量这样敏感信息和易变配置可以单独管理不用写死在编排文件里。我这份 .env 文件长这样# 数据库密码务必改成强密码 DB_PASSWORD这里改成你自己的强密码 # 平台内部密钥用于会话加密和签名 APP_SECRET这里生成一串足够长的随机字符串 # 大模型接口配置以讯飞星火为例 MODEL_API_KEY你的星火APIKey MODEL_API_BASEhttps://spark-api-open.xf-yun.com/v1生成随机密钥可以用这条命令openssl rand -base64 32模型接口的配置是很多人容易卡住的地方。掘金版默认支持对接讯飞星火大模型你需要在讯飞开放平台申请 API Key然后在控制台把服务器出口 IP 加入白名单。需要注意的是星火的接口地址以你申请服务时拿到的信息为准不同版本可能对应不同的域名和路径填错了模型调用就会报错。如果你的团队内网已经部署了 OpenAI 兼容接口的模型服务比如用 vLLM 或 Ollama 框架部署的开源模型也可以把 MODEL_API_BASE 指向内网模型服务的地址让 Astron 对接你们自己的模型。这种方式在完全内网隔离的环境下非常实用模型推理和数据全都不出内网。3.3 持久化与网络规划数据持久化是私有化部署的生命线。容器本身是无状态的一旦容器被删除容器内部的所有数据都会跟着消失。所以 postgres、redis、server 这三个服务都做了数据目录映射把容器内部的存储位置映射到宿主机的 ./data 目录下。这样即使容器被删掉重建数据依然在服务恢复后直接挂载原来的目录就能继续用。网络方面我这个版本里用了自定义网络 astron-net。自定义网络的好处是容器之间通过服务名互相访问比如 server 连接 postgres 时直接用主机名 postgresDocker 内置 DNS 会自动解析到对应的容器 IP。即使容器重启导致 IP 变化服务名也不会变配置不用跟着改。相比默认的 bridge 网络自定义网络的隔离性也更好系统外部的容器无法随意访问网络内的服务。备份的时候只需要备份整个 data 目录就可以了。我会把 data 目录做成定时快照比如用 cron 每天凌晨打包压缩一次保留最近 7 天的备份。这个习惯在后续升级和故障恢复时能救你一命。4. 部署执行与服务验证4.1 一键启动与日志观察所有配置准备好之后启动就很简单了cd /opt/astron docker compose up -d第一次执行时 Docker 会拉取镜像根据网络情况可能需要几分钟到十几分钟。拉取完成后容器会按依赖顺序启动。用下面的命令查看状态docker compose ps正常状态下所有服务的 STATUS 都是 Up并且 postgres 和 redis 的健康状态显示为 healthy。如果某个服务显示 Restarting 或者是 Exited说明启动过程有问题需要查看日志。查看日志是我排查问题最常用的手段# 查看后端服务的完整日志 docker compose logs -f server # 只看最近 50 行 docker compose logs --tail50 server启动阶段重点关注两件事第一server 是否成功连上了 postgres 和 redis第二数据库初始化是否执行成功。如果日志里出现 connection refused基本可以确定是依赖服务没就绪检查健康检查和 depends_on 配置。如果出现 migration failed 或类似的数据库迁移错误可能需要手动进容器执行迁移命令。容器日志会持续输出如果确认服务已经正常监听端口就可以进入下一步功能验证了。4.2 端到端功能验证与模型连通性测试服务起来了不代表真的能用我建议做一轮完整的端到端验证。第一步在浏览器里访问 http://服务器IP看到登录页面说明前端正常。首次登录需要初始化管理员账号按页面提示设置就行。如果页面能打开但接口请求报 502 或 504大多是反向代理没有正确转发到 server 容器检查 web 容器里 Nginx 的 upstream 配置或服务端口映射。第二步登录之后进控制台创建一个简单的 Agent。我会先不做复杂编排直接选一个基础模型在对话窗口里发一条消息测试连通性。如果返回正常说明模型接口配置没问题。如果报错先分清楚是模型 API Key 的问题、接口地址的问题还是网络白名单的问题。这里有个建议在浏览器里操作之前先用脚本确认模型接口本身是通的把问题范围缩小。如果你用的是星火 API可以用一个简单的 Python 脚本验证import requests url https://spark-api-open.xf-yun.com/v1/chat/completions headers { Authorization: Bearer 你的APIKey, Content-Type: application/json } payload { model: generalv3.5, messages: [{role: user, content: 你好请回复连接正常}], max_tokens: 50 } resp requests.post(url, headersheaders, jsonpayload, timeout30) print(resp.status_code) print(resp.json())这里的具体地址和模型名以你实际开通的服务为准。脚本能通说明 API Key 和网络没问题再回头检查平台侧的配置脚本不通问题大概率出在模型服务本身不需要在平台上折腾。第三步测试知识库功能。新建一个知识库上传一份 PDF 或 Word 文档等系统完成解析和向量化后基于这个知识库创建一个问答应用提问文档里的内容看能不能检索到并生成回答。这一步能同时验证文件存储、向量检索和模型生成整条链路是整套系统是否真正可用的关键验证。5. 常见问题与排查经验5.1 启动阶段的典型故障我整理了几类常见问题按出现频率排序。端口冲突是我遇到最多的问题尤其是 80 端口。很多服务器上已经跑了 Nginx、Apache 或者其他 Web 管理面板docker compose up 的时候会直接报端口被占用。处理方式很简单改编排文件里的端口映射就行。但要注意改完 web 的端口后页面访问时也要带上对应端口号避免访问不到。镜像拉取失败也是很常见的情况。要么是服务器网络访问 Docker Hub 不稳定要么是内网环境根本没有外网权限。前者可以配置 registry mirror 镜像源后者只能按我之前说的方式在能联网的机器上 docker save 再 load 导入。我自己的经验是内网环境一定要提前确认镜像获取策略等到部署时再想办法就来不及了。依赖服务未就绪导致的启动循环也值得注意。表现为 server 容器一直在 Restarting日志里反复出现数据库连接失败。这类问题要从两个方向解决一是确保 postgres 和 redis 的健康检查能通过二是确认 server 的环境变量里 DB_HOST、DB_USER、DB_PASSWORD 等配置跟 postgres 容器里的初始化配置一致。我自己就犯过只改密码没同步. env 文件的错误排查了半天才发现是配置不一致。5.2 数据持久化与版本升级的坑数据持久化这块最常见的问题就是忘记配置 volume。容器跑了一段时间后管理员删容器释放资源数据全部没掉这种教训非常惨痛。部署时一定要在编排文件里把三个数据目录映射好并且提前养成定期备份 data 目录的习惯。版本升级时要特别注意。我建议的升级流程是先备份 data 目录再 docker compose pull 拉取新版本镜像然后 docker compose up -d 让 Compose 重建有变化的容器。如果升级后发现问题把备份的 data 目录恢复再用旧版本镜像重新启动即可回滚。这里有一个核心原则任何时候都不要在没备份的情况下升级。锁版本号这个习惯一定要养成。我见过有团队用了 latest 标签过了几个月容器重启后自动拉到新版本数据库结构不兼容直接起不来。把镜像版本固定下来升级是主动的、可控的而不是被动的、意外的。5.3 安全加固与运维建议私有化部署在安全上也不能放松。首先不要把所有端口都暴露到公网。web 的 80/8080 端口如果需要对外提供服务建议在宿主机防火墙层面做访问控制只放行必要来源 IP。postgres 的 5432 和 redis 的 6379 端口完全不建议暴露到宿主机外部内部网络访问足够了。可以在编排文件里只配置内部网络不设置端口映射这样宿主机外部根本无法直接访问数据库和缓存。其次.env 文件里保存了数据库密码、API Key 等敏感信息要保证这个文件的权限只有运行用户可读写不要提交到 Git 仓库。如果团队有配置管理工具可以用密钥管理方案管理这些敏感信息。最后日志和数据备份要定期检查。我一般每周检查一次磁盘占用、日志大小和数据目录增长情况避免日志文件无限制增长把磁盘占满。如果日志量很大可以考虑在 Compose 里配置日志轮转参数比如logging: driver: json-file options: max-size: 50m max-file: 10这个配置能确保单个日志文件不超过 50MB最多保留 10 个文件防止日志无限膨胀。整套系统部署完成之后最花时间的其实不是执行命令而是理解服务之间的依赖关系和数据流转路径。先分清哪个服务负责什么、数据存在哪里、模型从哪接入后面遇到问题基本都能快速定位。我个人最大的体会是私有化部署的每一环都必须可重复、可回滚、可恢复做到这三点系统才算是真正可控的。