把 Agent 工作区交付到离线内网:安装包之外,还要验收什么?

把附件访问、依赖与恢复变成可复验的检查,再由接收团队签收。

Busabase Team
← 返回博客
把 Agent 工作区交付到离线内网:安装包之外,还要验收什么?

安装包已经拷进内网,容器启动了,登录页也能打开。接下来上传附件却失败,Agent 调用模型仍然连接外部服务,重启后还有数据需要重新配置。

离线交付需要验收的对象,远比“应用能启动”完整。Busabase 工作区、对象存储、授权、持久化,以及接入的 Agent、模型与工具,各有自己的依赖和网络路径。交付前把范围说明白,验收时才不会把一部分的成功当成整条链路已经就绪。

先界定交付边界

工作区本地化,解决的是记录、文档、附件和审核协作在哪里运行与保存。Agent 使用什么模型、连接什么工具,则取决于另外的部署与配置。

因此,先列出本次交付包含的组件,以及哪些能力会在隔离环境中使用。对于每项外部连接,明确是内网替代、停用,还是由获得授权的网络路径提供。没有确认的依赖保留为验收问题。

主权 AI 的架构价值需要落到这些具体责任上:谁提供模型,谁维护数据库,谁确认用户浏览器能访问附件,谁负责备份与恢复。工作区部署完成后,这些责任仍然存在。

访问路径与交接机制

选部署形态,也是在选交付清单

按当前离线安装说明,可以在联网环境准备镜像、导出 tar 文件和 SHA-256 校验文件,转移到目标主机后先验证完整性,再加载镜像。

all-in-one 镜像已经包含 Postgres 与 SeaweedFS。Compose 部署则还要准备相关依赖镜像,或配置可用的内部镜像仓库。只带应用镜像,可能不足以在完全隔离的网络里完成 Compose 启动。

交付清单应记录镜像版本或摘要、校验文件、依赖镜像、部署配置与持久化位置。实际镜像和命令以当前官方文档及团队批准的版本为准,不把一个会变化的 latest 标签当成长期验收依据。

校验文件证明转移后的文件是否一致;启动记录证明对应部署是否能运行。两种证据分别保留。

页面可用,不代表附件路径已经通了

浏览器访问应用和访问附件,可能走不同的请求路径。服务器能够访问对象存储,不代表用户浏览器也能使用返回的对象地址。

验收时,从实际使用的内网终端登录应用,再完成一次获准附件的上传和下载。检查请求指向的域名、协议、端口和证书是否对这台终端可用。不能只在服务器本机测试。

配置参考明确要求 APP_URL 与浏览器实际访问地址一致,包括协议、主机和端口。反向代理还应正确传递原始主机和协议。地址或 Origin 配置不一致,会影响登录;对象存储的访问地址则需要结合实际部署单独核对。

这两条链路应该分开留证:应用登录成功,附件上传成功,附件下载可读。不要用首页截图替代附件验收。

权限与执行边界

离线授权与全链路离线,是两次检查

当前安装文档说明,授权码在实例本地通过嵌入的公钥验证,激活不依赖联网请求。实施团队仍应核对具体授权码、使用范围和有效期,并按授权说明处理实际状态。

本地验证解决工作区自身的授权问题。Agent 所连接的模型 API、邮件服务、第三方工具或外部身份服务,仍需要各自检查。不能因为授权验证不联网,就承诺整套 Agent 系统完全不外联。

验收清单应逐项记录连接目标和允许的网络边界。断网后预期不可用的能力,也要在交付说明中清楚写明,让使用者知道系统边界。

用重启和恢复检查持久化

第一次写入成功,只能说明当前实例能够写入。交付还需要确认记录、附件、配置和必要凭据在重启后仍然可用。

all-in-one 的首次启动会生成相应凭据,当前配置文档指出其保存在 /data/.credentials,并要求备份。备份不应只考虑可见的文档内容,还应结合部署形态检查数据库、对象存储和配置。

恢复步骤按备份与恢复文档以及团队自己的运维规则执行。在获准的独立环境中验证恢复,确认记录与附件仍可读取,并保留恢复范围和结果。不要将“已有备份文件”写成“恢复已验证”。

在 Busabase 实例里,验收一次完整的知识交接

把团队说明保存在 Doc,把需要持续维护的业务条目放入 Base,把重复执行的方法保存在 Skill,再上传一份脱敏附件。这里建议的是最小验收材料:它们分别检查文档、结构化记录、可复用方法和对象存储,不要求照搬一套行业模板。

让获准的 Agent 读取这些资料,并通过 ChangeRequest 提议修改一条记录。编辑检查差异并接受后,回读正式记录,确认修改确实进入当前版本。接着从接收方的内网终端重新打开 Doc、读取记录和 Skill、下载附件,重启后再检查一次。验收对象是这些资料和修改历史能否留在交付的 Busabase 实例里;Agent、模型与连接工具能否离线执行,仍按各自的部署检查。

一份可以共同签收的检查单

以下是建议的验收项目,实际执行后才填写结果:

检查项要确认什么保留什么证据
文件转移镜像及依赖完整,版本可识别摘要、校验结果与交付清单
首次启动内网地址可访问,配置符合部署方式版本、配置记录与启动结果
用户操作实际终端能登录、读写获准记录操作结果与遇到的问题
审核协作提案、接受与 canonical 变化符合权限ChangeRequest 与记录回读
附件路径实际终端能上传、下载和读取请求目标与文件核验结果
隔离重启已声明能力在隔离状态下按预期恢复重启后记录和附件检查
备份恢复指定范围能够在独立环境恢复恢复步骤、范围与核验结果

由实施方与接收方共同确认未通过项的责任人和复验条件。测试材料应脱敏;部署凭据、授权码和对象存储密钥不应进入公开报告。

准备交付时,先按自己的部署形态列组件和网络路径,再把每一项变成可复验的动作。验收的结果应能解释:交付了什么、哪些已验证、还有哪些依赖需要接收团队接住。