Skip to main content

实施与运维要点

本页是部署方案与前提的命令与判据补充,内容取自《GIS Agent 离线部署用户手册》V3.25(2026-10-18)第八章技术附录。手册正文共 8 章、74 个层级标题、1746 行、47 条修订记录,本页只收实施现场每天会用到的部分。 出于安全约束,手册中涉及密钥注入的文件路径与配置字段名不在本文档展开;现场按厂商交付说明操作,本文只给不含敏感信息的验证方法。

三个离线包关系

三套离线包可以单独打包、单独传输、单独恢复,不是同一个安装包的三种模式。 局域网大模型场景的部署顺序是 数据库包 → 离线大模型包 → GIS Agent 包;公网场景可跳过离线大模型包,但数据库包和 GIS Agent 包仍然需要。 GIS Agent 离线包交付业务容器、配置、技能包、知识库运行文件、离线 Docker 镜像和必要的数据卷归档;部署脚本在目标机上加载镜像、同步运行配置、写入环境文件、恢复数据卷并启动服务。离线包不含大模型权重,也不负责启动大模型推理服务;数据库服务同样不由 GIS Agent 包安装。

bundle 内容

解压后先 chmod +x deploy.sh,再按 manifest.txt 核对包内镜像与卷归档。md5sum 需与出包侧记录值一致,不一致就重传,不要拆分或改名 bundle 内部目录。

deploy.sh 的职责边界

deploy.sh 按顺序执行 16 步,可概括为四组: 数据库地址有两种给法:显式 --database-url,或把数据库离线包 deploy.sh 生成的 database.env 放进 bundle 目录(或其上一级)自动复用 —— 后者是单机一体交付的推荐做法,日志会打印 复用数据库离线包的连接串:<路径>。注意 GIS Agent 包本身不含数据库镜像与服务,必须另有数据库离线包或客户自建 PostgreSQL。 数据库 TCP 预检失败时不会继续重建业务栈,会提示数据库服务状态、监听地址和防火墙检查项。--skip-up 仅用于生成或更新配置时跳过该预检。 常用参数共 5 个:
首次部署不要跳过管理员口令和 WebUI 口令,否则网关会在数据库连接成功后仍因认证未配置而退出。会话密钥不要求现场手工输入:目标机已有引用则保留,否则由 deploy.sh 自动生成随机值。 这份脚本只处理 GIS Agent 包本身,不负责生成或安装数据库包、离线大模型包。

数据卷规则

编排使用固定命名的 external volume,bundle 目录名变化不会创建同名新卷;deploy.sh 会在启动前创建缺失卷,并修复已有动态运行容器的 home 目录属主。禁止使用 docker compose down --volumes。如果只想保留目标机已有数据,部署时用 ./deploy.sh --skip-volumes。

部署后验收

容器状态

至少确认下面 7 个服务处于 Up 或 healthy: mapgis-ai-gisagent、postgis-gateway、knowledge-mcp-http、agent-opencode、agent-claude、agent-qwen-code、agent-qoder。 新版包的 deploy.sh 会自动等待上述服务健康;手工验收仍建议保留 docker logs --tail 120 <container>,因为健康检查不能替代模型 API、鉴权注入和会话非空回复的验收。

Web 入口

19081 固定由数据库离线包提供 SkillHub Web 页面;18081 保留给独立离线大模型包的 GPUStack UI / API;19080 是 SkillHub API,通常不直接给浏览器用户。GPUStack /healthz 成功只说明平台控制面可用,能否推理还取决于 worker、GPU 驱动、容器工具链、模型权重和推理后端。

会话验收

  • 公网模型:新建一次会话,确认能返回有效文本。无响应时优先排查模型 API 地址、密钥、模型 ID,以及容器到公网模型服务的连通性。
  • 局域网模型:额外确认内网模型网关可达、推理服务已加载模型、GPU 资源正常。无响应时优先排查内网地址、鉴权、模型 ID、GPU 状态和推理服务日志。
  • 口径:ACP session created 只表示会话建立成功,不表示模型调用成功。必须看到消息列表里出现非空 assistant 内容,才能判定对话链路完成。只有 ACP session created 而后没有有效回复,通常是模型调用阶段失败,而不是 Web 登录或握手失败。
局域网模型的完整链路是:GPUStack server → worker READY → 推理后端 → 模型 RUNNING → /v1/models → /v1/chat/completions → 业务侧模型接入 → 会话非空回复。缺任何一环都算未通。

授权验证

先区分两类授权:MapGIS SDK 授权(站点目录 RegKey / *.reg)缺失时 deploy.sh 只告警、不中断部署,补齐后重跑即启用;系统授权 license.lic 在部署之后从管理页上传,未授权只影响会话拉起。两者都不是部署失败。
首次登录后如果系统未授权,首页会提示”系统未授权,请在后台授权管理页面上传 license.lic”。这不是部署失败,而是需要补充服务器授权。按顺序执行:
  1. 访问 http://<对应IP>:17076/manager/。
  2. 点击 授权管理。
  3. 复制页面中的机器码,提供给厂商,用于签发绑定当前服务器的授权。
  4. 厂商收到机器码后分发对应的 license.lic。
  5. 回到授权管理页上传 license.lic,也可以直接粘贴其 JSON 内容。
  6. 点击 上传并校验,校验通过后返回首页确认未授权提示消失。
校验失败时优先确认机器码与当前服务器是否一一对应、文件是否为厂商签发且内容完整。

联网能力矩阵

下表按当前默认配置说明。若把模型地址改为客户内网的兼容接口,agent-* 的可用性需要按现场重新验证。 7 项能力中 4 项在纯局域网默认可用性为”不可用”,且全部集中在 agent-* 运行面;本地业务服务(知识库、网关、Web、授权)不受影响。纯局域网现场如果不能访问公网,实施人员只需要确认局域网模型接口和本地业务服务。 本表与离线部署:技能影响范围的 L1–L6 是两个口径:本表讲模型调用面(哪个 Agent 客户端能起来),L1–L6 讲制图产出面(页面、底图、字体、数据四个环节哪些会断)。离线交付时两张表都要过。

私网 Token 服务器运行期判据

以下判据来自局域网大模型包的实测取证,回答现场最常被追问的问题:对话报 Model not found or no running instances available,是不是部署坏了?结论是同一条报错有三种成因,处置方式完全相反,只有其中一种需要人工干预。 关键判据:容器 Up 与 /v1/models 返回 200 都不构成”模型可对话”的证据。验收和排障必须以一次真实的 POST /v1/chat/completions 往返为准。关闭看门狗或复位实例都会中断正在进行的对话,属于服务变更,需按现场变更流程执行。

宿主重启后日志要去容器标准输出取

宿主重启时推理容器由 Docker 重启策略自行拉起,而 worker 不会重新接管它的输出流。结果是:按修改时间排序”最新”的那份容器日志其实停在崩溃前一刻,末行是 cleaning up before exit——照它排障会拿到一份死证据。
容器启动时间晚于宿主启动时间,即 worker 未重新接管。

宿主内存是”到顶淘汰”,不是无界增长

长上下文推理把三类占用叠加在宿主内存上:跨会话的 prompt cache(受缓存字节上限约束)、上下文 checkpoint(默认 32 块)、模型权重在加载期的短暂驻留。缓存到顶时服务自行淘汰最旧条目,实测单次可释放 24 GB 量级,因此”内存一会儿逼近宿主上限、一会儿又回落”是正常锯齿,不是泄漏;淘汰会短暂阻塞请求处理。
memory.events 的 oom_kill 为 0 即说明这轮内存压力没有演变成 kill,不需要人工复位。运维要关注的不是”缓存会不会涨满”,而是该容器峰值留给桌面和其它服务的余量:实测单实例峰值可达 72 GiB 量级,在 96 GB 级宿主上只剩约 23 GB 给其余进程。 缓存占用没有单一的”每 token 多少内存”常数:同一份日志里,带满 checkpoint 的长会话条目约 195 KiB/token,不带 checkpoint 的条目约 47 KiB/token,差额几乎全是那 32 块 checkpoint。按缓存上限 32768(单位 MiB)换算,实际容量约为两个满上下文会话,第三个不同内容的长会话进来必然淘汰最旧的一个。因此不要因为”宿主还剩多少内存”去下调缓存额度:下调只会把跨会话的预填充复用换成更慢的冷启动,而不解决峰值余量。

并发与响应时间的读法

  • 并行度设为 1 且副本数为 1 时,同一时刻只有一个活跃解码会话;第二个用户不是”变慢”而是排队。实测一条 8 token 的极短请求在负载期间往返耗时 26.1 秒(HTTP 200 正常返回),空闲时应在秒级。
  • 不要用日志里的 t/s(解码吞吐)代表用户体感;上报体感问题时必须同时给端到端耗时。
  • 若响应”正好慢一倍”,优先排查镜像内置代理是否把同一请求执行了两次。
  • 日志字段陷阱:timings.prompt_n 不是提示词长度,命中缓存时它只计重新计算的那一段;统计提示词长度一律以 usage.prompt_tokens 为准。

参数取舍边界

  • 自适应显存开关在这类部署里是惰性开关:入口脚本恒定注入上下文长度与 offload 层数,自适应逻辑遇到已设值直接跳过。既不要指望它缓解显存压力,也不要断言关掉它会启动失败。
  • 上下文 checkpoint 的正确参数名是 --ctx-checkpoints N(简写 -ctxcp),--checkpoints-max 这个参数不存在,填错会让推理进程直接启动失败、实例更难恢复。
  • 下调显存看门狗阈值只会让重启更频繁;真正有效的余量手段是缩短上下文、减少 offload 层数、降低 checkpoint 块数或压缩 KV 缓存精度,均须由运维在变更流程内决定并逐项实测。
  • 开发机(96 GB 级宿主)上实测”能自愈”的结论不可平移到交付机型;交付最低配为双 RTX 5090 32G,而 64 GB 级内存机型在制图类技能上实测已占用宿主内存 95–97%。现场必须按交付机型实际内存重新核对峰值余量。

选型参考依据

Qwen3-235B-A22B-Instruct-2507-FP8 的官方模型卡给出总参数 235B、激活参数 22B、原生 262,144 tokens、仅非思考模式,并提供 vLLM / SGLang 的 OpenAI 兼容服务示例;官方 FP8 基准以 4 张 NVIDIA H20 96GB、TP=4 为参考。这应理解为模型装载和性能评估起点,不等同于现场生产配置。262,144 上下文会显著增加 KV Cache 和峰值显存压力,建议先以 32K 或 64K 完成上线验收。 GPUStack 侧需要额外确认:server 可运行在无 GPU 的 CPU 节点,worker 节点需要 Linux、GPU 驱动、Docker 和对应容器工具链;多 worker 分布式推理需要 server-to-worker、worker-to-server、worker-to-worker 网络连通;以默认配置为例,管理入口通常使用 TCP 80/443,worker 和推理服务还可能使用 10150、40000-40063 以及分布式 vLLM/Ray 的 41000-41999 端口范围。手册给出 5 条官方参考链接(Qwen 模型卡与部署文档、推理基准、GPUStack 安装要求与快速开始)。

默认值速查

常见问题定位方向

手册技术附录的常见问题表共 48 行现象,按类别归纳如下(现场按类别定位,再回手册查对应行): 手册中另有 14 行现象涉及登录口令、密钥或鉴权注入,属敏感配置范畴,本文只归类不展开具体文件名与字段名。这类问题的现场验证方式是不含敏感信息的:确认服务健康、确认凭据按交付说明注入、确认模型 ID 与实际模型服务一致、确认登录接口返回码。

不作为客户承诺的边界

以下内容必须由运维、网络和安全团队确认,手册不写成固定客户承诺(共 9 项):Linux 发行版与内核、CPU 架构(是否只支持 x86_64、是否需要 ARM)、PostgreSQL 版本与磁盘 IOPS、并发量、局域网模型的 GPU 与推理栈版本、高可用方案、企业安全(HTTPS / SSO / LDAP / 审计)、数据增长与磁盘扩容、备份与升级策略。 本页与部署方案与前提、x86 + 银河麒麟 V11、龙芯 + 统信 UOS、技能影响范围共同构成离线交付的完整检查面;五页都以同一份手册与技能包扫描结果为事实源,手册升版后需同步刷新。