最近在折腾内部知识库助手的时候正好拿到了讯飞 Astron Agent 掘金版的私有化部署包。这套东西说白了就是讯飞星火大模型生态里的智能体开发平台你可以把它理解成一个“Agent 工厂”——在网页上拖拖拽拽、配配提示词、挂上工具和知识库就能生成一个能对话、能查资料、能调用外部接口的 AI 应用。掘金版则是面向开发者社群的尝鲜版本支持 Docker Compose 一键私有化部署对我这种数据不出内网强迫症选手来说非常对味。这篇文章就把我这两天从零到一部署的完整过程写出来包括服务器要什么配置、Docker 环境怎么准备、部署包怎么解压、compose 文件怎么改、启动时踩了哪些坑以及最终怎么验证服务可用。内容不是那种官方手册的复述全部来自我自己的实操记录适合有一定 Linux 和 Docker 基础的开发者参考当然纯新手照着我这个步骤一步步来也能把环境跑起来。1. 部署前必须想清楚的三件事1.1 Astron Agent 掘金版到底是什么先说清楚这个东西的定位免得你上手之后一头雾水。Astron Agent 是一个面向智能体开发的全栈平台底层调用讯飞星火大模型的推理能力上层提供 Agent 编排、知识库管理、插件工具注册、对话调试等一整套功能。你可以在里面创建不同角色的 Agent给它们设定人设和指令再挂上知识库文档或者 HTTP 插件最后通过 API 或者嵌入式对话组件对外提供服务。掘金版是讯飞开放平台对外发的一个可私有化部署的分发版本和云端 SaaS 版相比核心差异在于数据和运行环境都在你自己的服务器上不依赖外部网络调用平台服务仅在与星火模型交互时需要联网或者你也可以在配置里改成内网模型网关。这一点对很多企业场景非常关键尤其是知识库里有内部制度、产品手册这类敏感资料时数据不出内网往往是一条硬性要求。1.2 为什么选择 Docker Compose 而不是单机安装部署这套系统其实有几种方式官方可能提供一键安装脚本也可能是 Helm Chart 给 Kubernetes 用的再有就是我这篇文章要讲的 Docker Compose。个人体验下来Compose 方案在中小型服务器上是最平衡的选择。Kubernetes 那一套在单机或者三五台机器的场景下纯属杀鸡用牛刀光维护 etcd、kubelet 就够你喝一壶的。而传统的手工安装需要自己装 JDK、Node、PostgreSQL、Redis、向量数据库还要处理版本冲突和环境变量一个版本不对就能让你排查到怀疑人生。Docker Compose 的好处是它把整个系统拆成若干个容器每个容器只跑一个进程依赖关系通过 compose 文件声明docker compose up -d一下所有服务就像一个整体一样拉起来日志统一管理数据卷固定挂载后边升级和回滚也方便得多。1.3 这套部署方案对服务器有什么硬性要求我强烈建议你在部署之前先对着下面的清单核对自己的机器别等启动报错了才想办法。掘金版虽然是“轻量版”但 AI 平台跑起来以后模型服务的中间层、向量化检索、前端构建产物哪一个都不省心。项目最低配置推荐配置说明CPU4 核8 核及以上并发调用 Agent 时 CPU 消耗明显内存16 GB32 GB低于 16G 非常容易 OOM尤其是向量库和数据库同时跑的时候磁盘100 GB200 GB SSD镜像、日志、知识库文件都会吃空间SSD 对检索速度提升明显操作系统Ubuntu 20.04 / CentOS 7.9Ubuntu 22.04Linux 内核 5.x 以上对 Docker 兼容性更好Docker20.1024.0太老的 Docker 对 Compose v2 支持不好网络能访问外网带宽 ≥ 10 Mbps首次安装需要拉镜像调用星火大模型也需要出网如果你是拿自己手头的虚拟机或者云服务器来试只要满足推荐配置基本上跑起来不会太吃力。要是配置差一截也别灰心后面我专门写了怎么限制容器资源占用能让它在低配机器上也能勉强跑起来。2. 环境准备与部署包预处理2.1 先给服务器“洗个澡”基础环境初始化拿到一台全新服务器之后别急着装 Docker先把系统基础环境理顺。我这边用的是 Ubuntu 22.04下面所有命令都是基于这个版本CentOS 的差异我会在括号里标注出来。登录服务器后第一步更新系统软件源然后安装一些常用工具。curl、wget、vim、lsof、net-tools这几个属于排查问题必备强烈建议一次装齐免得到时候现找包。sudo apt update sudo apt upgrade -y sudo apt install -y curl wget vim lsof net-tools uuid-runtime紧接着做两件事关闭 swap 或者至少把 swappiness 调低。虽然对 Agent 平台来说 swap 不是完全不能用但在内存捉急的机器上swap 一开启就会导致容器频繁换页响应速度变得非常“感人”。我的习惯是保留一点 swap 兜底但把 swap 使用倾向调低# 查看当前值 cat /proc/sys/vm/swappiness # 临时调低 sudo sysctl vm.swappiness10 # 永久生效 echo vm.swappiness 10 | sudo tee -a /etc/sysctl.conf然后是文件句柄和进程数限制。容器跑起来以后如果知识库文件特别多向量化进程会打开大量文件句柄默认的 1024 限制根本不够用很容易出现 “Too many open files” 报错。顺手把硬限制调高# 查看当前限制 ulimit -n # 追加到 /etc/security/limits.conf echo * soft nofile 65535 | sudo tee -a /etc/security/limits.conf echo * hard nofile 65535 | sudo tee -a /etc/security/limits.conf改完之后退出终端重新登录让配置生效。2.2 安装 Docker 与 Compose 插件Docker 安装我习惯用官方脚本简单直接不需要纠结适配源的问题。但这里也提醒一句官方脚本在国内网络环境下偶尔会超时如果你遇到这种情况就换用阿里云或者腾讯云的镜像源安装脚本原理都一样。# 官方安装脚本 curl -fsSL https://get.docker.com | sudo sh装完之后先别急着把普通用户加进 docker 组先把 Docker 服务启动再看版本号sudo systemctl enable --now docker docker --version docker compose version这一步一定要确认docker compose命令存在注意中间有个空格不是老版本的docker-compose。新版本的 Docker 默认都带 Compose v2 插件如果你的环境里没有手动装一下也很快sudo apt install -y docker-compose-plugin验证版本能看到类似Docker Compose version v2.24.0的输出就没问题了。个人习惯把当前用户加进 docker 组这样不用每次敲sudo dockersudo usermod -aG docker $USER newgrp docker这里有个小坑加完组之后当前 SSH 会话不一定立刻生效最稳妥的做法是断开重连免得下面的命令还是权限报错。2.3 解压部署包与目录规划讯飞开放平台上下载到的 Astron Agent 掘金版部署包通常是一个 tar.gz 压缩包大小在 1-2 GB 左右里面除了 docker-compose.yml 之外还包含镜像文件、配置文件模板和一份部署文档。收到之后先别急着解压到系统盘根目录我建议规划一下目录结构。我自己习惯的目录规划是这样的/data/astron-agent/ ├── conf/ # 配置文件 ├── data/ # 数据持久化目录 │ ├── postgres/ │ ├── redis/ │ └── vector-store/ ├── logs/ # 日志目录 ├── images/ # 镜像 tar 包 ├── docker-compose.yml └── .env创建完目录之后把部署包解压进去mkdir -p /data/astron-agent cd /data/astron-agent tar -zxvf astron-agent-digging-version.tar.gz解压完后不要立刻启动先做两件很关键的事情第一查看部署包里的镜像 tar 文件确认镜像是否已经打好第二查看 compose 文件和环境变量模板了解默认配置。如果部署包里带的是镜像 tar 包就需要先把镜像导入本地 Docker# 进入镜像目录 cd /data/astron-agent/images # 逐个导入 .tar 文件 for img in *.tar; do docker load -i $img done # 验证镜像是否导入成功 docker images导完之后应该能看到astron-agent-*开头的一串镜像比如astron-agent-server、astron-agent-web、astron-agent-vectordb之类的。确认镜像都在下一步再改配置就是正确的姿势如果你还没导入镜像就急着docker compose upcompose 会尝试从远程仓库拉取不存在的镜像白白浪费时间。3. Docker Compose 部署实操全流程3.1 配置 .env 环境变量文件之前先弄懂每个参数的含义Compose 部署的精髓在于.env文件——所有跟当前环境相关的配置都抽出来放在这里避免把 IP、密码、端口硬编码在 compose 文件里。部署包里一般自带.env.example这个模板直接复制一份再改就行cd /data/astron-agent cp .env.example .env vim .env下面逐个说明几个核心参数你在修改的时候千万别随手乱填每一项后面都有讲究。先看端口和访问相关的配置# 对外暴露的端口 ASTRON_WEB_PORT8080 ASTRON_API_PORT8081 # 服务绑定地址 ASTRON_BIND_IP0.0.0.0ASTRON_WEB_PORT这个变量控制前端登录页的访问端口ASTRON_API_PORT控制后端 API 服务的端口。如果你的服务器上还有 Nginx 或者别的 Web 服务要注意端口冲突建议先用lsof -i :8080查一下端口占用情况再决定用哪个端口。再看数据库和缓存的密码配置# PostgreSQL 配置 POSTGRES_DBastron POSTGRES_USERastron POSTGRES_PASSWORDChangeMe_Strong_Password # Redis 配置 REDIS_PASSWORDChangeMe_Redis_Password这两个密码一定要改尤其是数据库密码。很多人在内网部署图省事用默认密码结果被扫描器命中数据库直接被人拖走。虽然 Astron Agent 的数据库默认只在内网监听但小心驶得万年船密码还是用强随机串生成比较好# 生成 32 位随机密码 openssl rand -base64 32还需要配置模型网关地址这是整个部署里唯一可能需要联网的环节# 星火大模型 API 配置 SPARK_API_KEY你的星火APIKey SPARK_API_SECRET你的星火APISecret SPARK_APP_ID你的星火AppID SPARK_API_BASEhttps://spark-api.xf-yun.com/v3.5如果你是内网部署且不想走公网也可以把SPARK_API_BASE指向内网的大模型网关这样数据链路就全部留在内网了。不过掘金版默认配套的还是星火公有云 API所以这三项信息需要提前去讯飞开放平台控制台创建应用获取。最后是管理员账号初始化配置ASTRON_ADMIN_USERNAMEadmin ASTRON_ADMIN_PASSWORD初始管理员密码 ASTRON_ADMIN_EMAILadminexample.com这一步会在首次启动时自动创建管理员账号密码同样是建议改成一个强密码登录进去之后再在系统里修改也行。3.2 docker-compose.yml 结构拆解别只顾着 up 起来修改完.env之后打开docker-compose.yml看一眼结构这能帮你在服务起不来的时候快速判断是哪个容器的问题。掘金版的 compose 文件一般情况下包含四个核心服务前端 Web、后端 API、PostgreSQL 数据库、Redis 缓存再加上一个可选的向量检索服务。version: 3.8 services: postgres: image: astron-agent-postgres:latest container_name: astron-postgres restart: always environment: POSTGRES_DB: ${POSTGRES_DB} POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} volumes: - ./data/postgres:/var/lib/postgresql/data networks: - astron-net redis: image: astron-agent-redis:latest container_name: astron-redis restart: always command: [redis-server, --requirepass, ${REDIS_PASSWORD}] volumes: - ./data/redis:/data networks: - astron-net api: image: astron-agent-server:latest container_name: astron-api restart: always depends_on: - postgres - redis environment: SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/${POSTGRES_DB} SPRING_DATASOURCE_USERNAME: ${POSTGRES_USER} SPRING_DATASOURCE_PASSWORD: ${POSTGRES_PASSWORD} SPRING_DATA_REDIS_HOST: redis SPRING_DATA_REDIS_PASSWORD: ${REDIS_PASSWORD} SPARK_API_KEY: ${SPARK_API_KEY} SPARK_API_SECRET: ${SPARK_API_SECRET} SPARK_APP_ID: ${SPARK_APP_ID} SPARK_API_BASE: ${SPARK_API_BASE} ports: - ${ASTRON_API_PORT}:8080 volumes: - ./data:/app/data - ./logs:/app/logs networks: - astron-net web: image: astron-agent-web:latest container_name: astron-web restart: always depends_on: - api ports: - ${ASTRON_WEB_PORT}:80 environment: API_BASE_URL: http://api:8080 networks: - astron-net networks: astron-net: driver: bridge几个关键点值得展开说一下。depends_on这个配置只是控制容器的启动顺序它不保证依赖服务已经“可用”。什么意思就是postgres容器虽然起来了但 PostgreSQL 进程可能还在初始化中API 容器这时候去连数据库就很有可能报连接被拒绝。对于这种情况比较靠谱的做法是依赖容器自身的健康检查机制如果 compose 文件里没写healthcheck那 API 容器就得有重试机制否则首次启动偶发失败就很正常。restart: always的意义很多人会忽略。它的作用是容器非正常退出后自动重启对于 API 这种可能因为启动时序问题首次启动失败的服务来说非常关键。但如果数据库持久化目录的权限不对导致反复启动失败它就会一直处于Restarting状态在docker ps里看起来特别扎眼。数据卷的挂载方式也值得说一句。这里用的是相对路径挂载也就是把宿主机的./data/postgres挂到容器里的数据目录。好处是备份恢复只要打包宿主机目录就行不用进容器操作。但相对路径有个坑——它依赖于你执行docker compose命令时所在的目录如果你在别的目录执行docker compose -f /data/astron-agent/docker-compose.yml up所有相对路径都会按当前目录解析数据就写到别处去了。所以我的建议是进入部署目录之后再执行所有 compose 命令或者干脆把路径写成绝对路径。3.3 首次启动从 empty 到 Running配置检查完毕镜像确认导入接下来就是启动时刻。先启动并观察日志cd /data/astron-agent docker compose up -d-d参数让服务在后台运行。第一次启动建议同时打开另一个终端用docker compose logs -f实时观察输出以便及早发现问题。如果 API 容器首次启动失败不用慌先看日志# 查看所有服务状态 docker compose ps # 查看 API 服务日志 docker compose logs -f api比较理想的启动过程是postgres 容器先进入 healthyredis 容器也就一两秒然后 api 容器开始等数据库连接、初始化表结构、加载模型配置最后 web 容器启动并反向代理到 API。整个时间大概在两到三分钟主要耗时在数据库初始化和模型配置加载上。如果一切顺利你会在日志末尾看到类似这样的输出astron-api | [main] INFO c.i.a.AstronApplication - Started AstronApplication in 45.12 seconds astron-web | [nginx] - start worker process 123 astron-web | [nginx] - start worker process 124这时候执行docker compose ps所有容器状态都应该是Up或者healthy。然后打开浏览器访问http://服务器IP:8080就能看到 Astron Agent 的登录界面用.env里配置的管理员账号登录系统会引导你完成初始化设置。3.4 使用 Nginx 反向代理与 HTTPS 配置如果你不只是自己本地试试而是想给团队用我强烈建议在 Astron Agent 前面加一层 Nginx 反向代理统一入口、统一 HTTPS 证书、还能做端口转发和 WebSocket 支持。Agent 平台的对话功能基本都走 WebSocket所以 Nginx 配置里有两行很关键server { listen 443 ssl; server_name agent.example.com; ssl_certificate /etc/nginx/ssl/agent.example.com.crt; ssl_certificate_key /etc/nginx/ssl/agent.example.com.key; # 前端页面 location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # WebSocket 代理 location /ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } }这里面的关键点在于proxy_read_timeout和proxy_send_timeout一定要设置足够长的时间否则 Agent 回答一个复杂问题时耗时超过默认的 60 秒Nginx 就会主动断开连接用户刚在界面上看到“正在思考”就被掐断非常影响体验。4. 踩坑实录与性能调优经验4.1 端口冲突与防火墙拦截第一次部署时遇到的最常见问题就是端口被占用。有些服务器上预装了 Nginx、Tomcat 之类的服务8080 和 8081 早就被占用了。这时候docker compose up并不会直接报错而是静默失败——容器起来了但端口绑定失败。排查命令很简单# 查看端口占用情况 lsof -i :8080 # 或者 netstat -tunlp | grep 8080确认端口被占用后要么把原来的服务停掉要么修改.env里的端口号再重新启动。修改端口号后记得执行docker compose up -d重建否则配置不会刷新。另一个容易被忽略的问题是云服务商的防火墙策略。你在本地curl http://localhost:8080能通但换到浏览器上外网访问不通八成就是云安全组策略没放行 8080 端口。这个跟服务本身没有关系去云控制台的安全组里添加入站规则就行。4.2 数据库初始化失败权限、编码和时区PostgreSQL 容器启动时偶发初始化失败这是我遇到过的第二个高频问题。表现是 postgres 容器一直重启日志里报FATAL: data directory /var/lib/postgresql/data has invalid permissions。这个问题的根源在于宿主机挂载目录的所有者权限和容器内 PostgreSQL 进程的用户不一致。容器内的 postgres 用户 UID 通常是 999而宿主机目录的所有者默认是 root导致容器内进程无法写入数据目录。解决办法很简单直接把数据目录的所有者改成 999 即可sudo chown -R 999:999 /data/astron-agent/data/postgres改完再启动docker compose up -d postgres数据库初始化还有一个时区和编码的问题。如果你发现数据库里的时间跟本地时间差了 8 个小时多半是数据库容器的时区没有设置。在.env里补上POSTGRES_TIMEZONEAsia/Shanghai同时数据库内部的初始化脚本里最好显式声明在 compose 文件的 postgres 服务下增加environment: TZ: Asia/Shanghai PGTZ: Asia/Shanghai4.3 内存不够容器 OOM 排查与限制前面说了掘金版推荐 32 GB 内存是有道理的。如果服务器只有 16 GB跑起来就会看到内存告急API 容器时不时被杀掉日志里出现Killed字样或者docker inspect里OOMKilled: true。如果你只能在低配机器上跑我的建议是给容器设置内存限制避免单个服务把整台机器拖垮services: api: deploy: resources: limits: memory: 4G reservations: memory: 2G但这里有个注意事项Compose 限制内存对于 Java 应用来说有个坑——容器里的 JVM 默认按照宿主机内存的 1/4 来分配堆内存而不是根据容器的 cgroup 限额。所以即使你给容器限制 4G 内存JVM 还是可能试图分配 8G 堆导致容器启动没多久就 OOM。解决办法是在 API 服务的启动命令里显式设置 JVM 参数environment: JAVA_OPTS: -Xms2g -Xmx3g -XX:UseG1GC这个技能点我踩了好几次才真正理解分享出来是希望你别在同一个坑里浪费一晚上。压低内存之后并发能力会下降但至少服务能稳定运行。如果后面业务量增长了再扩容服务器也不迟。4.4 数据备份与恢复私有化部署的兜底安全网数据是私有化部署最值钱的资产没有之一。Agent 平台的数据主要在两个地方PostgreSQL 里存的是用户、角色、Agent 配置、对话记录./data目录下存的是知识库文档和向量索引。所以备份要两部分同时做。PostgreSQL 的备份我推荐用容器内自带的pg_dump命令不需要在宿主机安装任何客户端docker exec astron-postgres pg_dump -U astron astron -F c -f /tmp/backup.dump docker cp astron-postgres:/tmp/backup.dump /data/astron-agent/backup/恢复的时候反过来docker cp /data/astron-agent/backup/backup.dump astron-postgres:/tmp/backup.dump docker exec astron-postgres pg_restore -U astron -d astron --clean /tmp/backup.dump挂载目录的数据就简单了直接用tar打包整个./data目录备份到其他盘或者对象存储里tar -czf astronomer_data_$(date %Y%m%d).tar.gz /data/astron-agent/data我在实际运维时用 crontab 做了每日凌晨自动备份保留最近 7 天的备份文件这样即使哪天手滑把数据改了也有后悔药吃。4.5 容器日志膨胀与定期清理容器跑久了之后日志文件会越来越大。默认情况下 Docker 的日志驱动是json-file如果不对它做大小限制半年下来日志文件动辄几十 GB磁盘空间被悄悄吃光服务不报错也莫名其妙变卡。在/etc/docker/daemon.json里加上日志轮转配置{ log-driver: json-file, log-opts: { max-size: 50m, max-file: 3 } }修改完重启 Docker 服务sudo systemctl restart docker注意这个配置只对新建容器生效已有的容器需要重建才会启用新的日志策略docker compose down docker compose up -d如果不想重建容器也可以手动清理当前日志truncate -s 0 $(docker inspect --format{{.LogPath}} astron-api)这条命令会把容器的 JSON 日志文件清空但保留文件本身不影响容器的正常日志输出可以放心使用。5. 部署完成后的功能验证与使用心得5.1 用随机对话验证 Agent 是否真正“通”了服务全部起来、页面能打开、账号能登录还不算大功告成至少得用一个完整的对话来验证链路是否通畅——也就是前端到 API、API 到模型网关、模型网关返回结果再回到前端这一整条链路。登录系统之后进入 Agent 编排界面系统会预置一个默认的空 Agent。你可以直接点开测试对话框输入一个最简单的提示词比如“你好介绍一下你自己”。如果收到符合预期的回复说明链路通畅模型调用正常。然后再测一下知识库功能在知识库管理里上传一份 PDF 文档等待向量化完成然后绑定到 Agent 上再提问文档里的具体内容看能否命中。这一步能同时验证文档解析、向量化、检索、大模型生成的完整闭环。有一个小经验首次提问的时候模型响应可能会慢一些因为要等向量库完成检索还要经过多轮上下文拼接这是正常现象。如果超过 30 秒还没响应就要回头查一下 API 日志看看是不是调用模型网关超时了。5.2 从部署者到使用者掘金版给我的几个惊喜整个部署过程跑下来抛开踩坑的部分Astron Agent 掘金版在产品完成度上确实给了我一些惊喜。第一个是 Agent 编排界面做得很直观没有太多复杂概念把“指令”“知识库”“技能插件”三个模块配置好一个能用的 Agent 基本就成形了。对于不是专业算法出身的业务人员来说这个学习曲线很低。第二个是内置的调试工具非常实用。在测试侧边栏里可以看到每一次对话的完整链路日志包括提示词最终拼装成了什么、调用了哪个知识库、命中了哪段文本、模型返回的 token 数是多少。这种透明感对开发者很友好排查问题不必靠猜。第三个是插件机制设计得相对开放。除了平台内置的 HTTP 插件和数据库插件之外你还可以自定义插件注册把内部系统接口包装成工具给 Agent 调用。这意味着你不只是能搭一个聊天的玩具而是真的能把 Agent 接入到业务系统里做一些自动查询、自动填单之类的实际工作。写在最后这套方案值不值得抄作业如果你手头有闲置的服务器或者正想在公司内网搭一套 Agent 开发平台讯飞 Astron Agent 掘金版配 Docker Compose 私有化部署这套方案我个人认为是值得一试的。Docker Compose 带来的运维便利是实实在在的从拉镜像到服务全起命令不超过五条比起一坨屎山一样的安装脚本不知道高到哪里去了。而私有化部署带来的数据自主可控对于有合规要求的场景来说更是刚需中的刚需。试完整个流程我最深的体会是这类“一站式 Agent 平台”最大的价值不在于它比裸写代码省了多少时间而在于它把最佳实践沉淀成了可配置的默认项——向量检索、上下文管理、工具调用编排、权限控制这些曾经需要自己一行行实现的底层能力开箱即用。你只需要把精力放在业务本身这大概才是平台类产品该有的样子。