> ## Documentation Index
> Fetch the complete documentation index at: https://gisagent.mapgis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 部署方案与前提

> 私有化部署要准备几台服务器、每台做什么、网络怎么连、部署前检查什么

# 部署方案与前提

> 本页与[离线部署：技能影响范围](https://gisagent.mapgis.com/docs/offline-deploy.md)配对使用。那页回答"技能层面哪些环节会在离线时断"，本页回答"要准备几台机器、每台做什么、网络怎么连、部署前检查什么"。
> 内容取自《GIS Agent 离线部署用户手册》V3.25（2026-10-18）第一至第六章；命令级细节、实际案例与故障处理见[实施与运维要点](https://gisagent.mapgis.com/docs/offline-deploy-ops.md)，信创现场见[x86 + 银河麒麟 V11](https://gisagent.mapgis.com/docs/offline-deploy-kylin.md) 和[龙芯 + 统信 UOS](https://gisagent.mapgis.com/docs/offline-deploy-loongarch.md)。

一句话结论：私有化部署通常按 **3 台机器** 规划——数据库服务器、GIS Agent 业务服务器、Token 服务器。三台机器职责分离，用户只访问 GIS Agent 业务服务器。

## 三机职责

| 机器 | 主要组件 | 项目推荐配置 | 说明 |
| :- | :- | :- | :- |
| 数据库服务器 | PostgreSQL / PostGIS | **16 核、32GB 内存** | 不安装 GPU；磁盘按数据量、IOPS 和备份周期由运维评估 |
| GIS Agent 业务服务器 | `postgis_gateway`、`gisagent`、`agent-acp` | **32 核、64GB 内存以上** | 重点保障节点；不需要 GPU，内存不足会影响 Agent、ACP、技能和并行任务 |
| Token 服务器 | 公网 API 或 GPUStack + 本地大模型 | 公网不需要本地 GPU；私网按模型与显存配置 | 私网模型单独部署，不放入数据库包或 GIS Agent 包 |

公网模型场景下，Token 服务器可以是外部模型服务，不一定单独采购本地机器；私网模型场景必须单独准备 GPU Token 服务器。

## 服务器数量随方案变化

| 方案 | 服务器数量 | 是否需要公网 | 是否需要 GPU |
| :- | :- | :- | :- |
| 私有化 + 局域网大模型 | 通常 3 台 | 不需要 | Token 服务器需要 |
| 私有化 + 公网大模型 | 通常 2 台 | GIS Agent 需要访问公网模型 API | 不需要本地 GPU |
| 已有数据库和公网模型 | 1 台 GIS Agent 业务服务器 | 需要 | 不需要 |

数据库已由客户提供、且使用公网大模型时，我方只需要 1 台 GIS Agent 业务服务器。

## 我方提供什么

离线包全部由我方提供，实施人员不需要自行制作安装包：

* 数据库离线包
* GIS Agent 离线包
* 局域网大模型离线包（只有使用局域网大模型时需要）

部署顺序固定为 **数据库 → 局域网模型（如有）→ GIS Agent**。

## 实施只需记住这一条链路

```text theme={null}
用户浏览器 -> GIS Agent 业务服务器 -> 数据库服务器
```

使用局域网大模型时再增加一跳：

```text theme={null}
GIS Agent 业务服务器 -> Token 服务器
```

用户不直接访问数据库和模型服务器。

## GIS Agent 业务服务器配置

| 项目 | 最低配置 | 推荐配置 |
| :- | :- | :- |
| CPU | 16 核 | **32 核** |
| 内存 | 32GB | **64GB 以上，优先加大内存** |
| 磁盘 | 100GB 可用空间 | 200GB 以上 |
| GPU | 不需要 | 不需要 |
| 软件 | Linux、Docker、`docker compose` | 同左 |

这台机器运行 `postgis_gateway`、`gisagent`、`agent-acp`、Web 和知识库服务。采购和扩容遵循"内存优先"，同时保证磁盘空间、Docker 和容器网络可用。

## 数据库服务器

优先使用客户现有的 PostgreSQL / PostGIS；没有现成数据库时，使用我方数据库离线包部署。本项目按 **16 核、32GB 内存** 规划，磁盘容量、IOPS、PostgreSQL 版本和备份资源由运维按数据量确认。数据库服务器不要与 GPU 模型服务器混用，除非项目已单独确认。

## Token 服务器

Token 服务器只在需要独立模型服务或私网大模型场景时准备。公网方案只需要可访问模型 API；私网方案需要 GPU、驱动、推理引擎和模型权重。

| 场景 | 推荐模型 | 参数 / 上下文 | 实施口径 |
| :- | :- | :- | :- |
| 公网 | `Qwen3.7-plus` | 以服务商当前规格为准 | 只确认 API 地址、模型 ID、密钥和网络出口 |
| 私网高配 | `Qwen3-235B-A22B-Instruct-2507-FP8` | 总参数 235B、激活参数 22B、原生 262,144 tokens（约 256K），非思考模式 | 按 4 张 96GB 级别 GPU、TP=4 做首轮评估；256K 与多并发需更大显存或 8 卡方案压测 |
| 私网回退 / 验证基线 | `Qwen3.8-27B-FP8` | 以现场已验证版本为准 | 双 `5090D` 或等效多卡；多人需要排队，不代表可承载 235B 模型 |

GIS Agent 包对模型能力的最低要求是不低于 `Qwen3.8-27B-FP8`。首次验收建议先以 32K 或 64K 上下文启动，确认显存、延迟和工具调用稳定后再提高到 256K。GPU 型号、卡数、显存和并发能力不作为固定客户承诺，最终以 GPUStack、vLLM / SGLang、GPU 厂商兼容矩阵和现场压测结果为准。

## 网络结构与端口

### 访问关系

| 起点 | 终点 | 端口 | 是否需要放通 | 用途 |
| :- | :- | :- | :- | :- |
| 用户 / 运维电脑 | GIS Agent 业务服务器 | `17076/TCP` | 需要 | 访问 Web、登录和授权管理 |
| 用户 / 运维电脑 | 数据库服务器上的 SkillHub Web | `19081/TCP` | 按需 | 访问技能管理页面 |
| GIS Agent 业务服务器 | 数据库服务器 | 数据库离线包通常为 `18084/TCP`；客户原生 PostgreSQL 按实际端口 | 需要 | `postgis_gateway` 和业务服务访问 PostgreSQL / PostGIS |
| GIS Agent 业务服务器 | 私网 Token 服务器 | 模型 API 端口，按 GPUStack 配置 | 私网模型需要 | 调用局域网大模型 |
| GIS Agent 业务服务器 | 公网 Token / 模型 API | `443/TCP` | 公网模型需要 | 调用 `Qwen3.7-plus` |
| 外部用户 | 数据库原生端口 / 模型 API | 任意 | 不需要 | PostgreSQL 和模型服务不直接对用户开放 |

模型 API 端口由 GPUStack 或现场模型网关决定，实施时填写实际端口，不要直接套用 `17076`。

### GIS Agent 内部端口

以下端口默认只给容器或内网服务使用，不需要对客户办公网开放。

| 端口 | 用途 |
| :- | :- |
| `3333` | PostGIS gateway / 瓦片服务 |
| `18088` | Knowledge MCP |
| `17074` | agent-opencode 内部服务 |
| `19080` | SkillHub API，通常只由 `skillhub-web` 调用 |
| `18081` | GPUStack UI / API，由离线大模型包提供 |

### 网络配置判断要点

* 局域网大模型：GIS Agent 能访问数据库和 Token 服务器即可，不要求访问公网。
* 公网大模型：GIS Agent 能访问公网模型 API 的 `443` 端口即可，不需要 GPU 模型服务器。
* 用户只访问 GIS Agent 的 `17076`，不要让用户直接访问数据库和模型服务器。
* 私网三台服务器之间必须有路由，防火墙按上表放行；GPUStack 管理端口只对运维网或 GIS Agent 开放。
* 多机部署时 GIS Agent 通过数据库服务器的 IP/DNS 和 TCP 端口访问 PostgreSQL，不使用数据库容器名、跨主机 Docker network 或数据库服务器上的 `localhost`。
* 数据库离线包的端口映射通常是 `18084:5432`，因此连接地址写成 `<数据库服务器IP或DNS>:18084`；客户提供原生 PostgreSQL 时填实际监听端口，不能机械套用 `18084`。

## 公网大模型和局域网大模型怎么选

| 判断条件 | 选择 |
| :- | :- |
| 数据不能出客户网络，现场不能访问公网 | 局域网大模型 |
| 需要私有化部署和本地推理 | 局域网大模型 |
| 现场允许访问公网，希望快速上线 | 公网大模型，推荐 `Qwen3.7-plus` |
| 不希望准备 GPU 服务器 | 公网大模型 |
| 希望模型参数量尽量大，且数据不能出网 | 私网 `Qwen3-235B-A22B-Instruct-2507-FP8` 规划方案 |

局域网方案把数据留在客户内网，并可以规划更大参数量的模型，代价是需要 GPU、显存、推理引擎和模型运维；公网方案不需要本地 GPU、接入更快，但依赖公网、密钥和第三方服务。两类方案共用同一套 GIS Agent 离线包，GIS Agent 只调用模型服务，不负责模型推理。

## 实施前客户需要提供什么

| 类别 | 客户提供内容 |
| :- | :- |
| 服务器 | GIS Agent 业务服务器、数据库服务器、Token 服务器（按方案准备） |
| 网络 | 服务器 IP、路由、防火墙放行和 DNS / 主机名解析 |
| 软件 | Linux、Docker Engine、Docker Compose v2 |
| 数据库 | PostgreSQL 连接地址、端口、账号和口令；或允许部署数据库离线包 |
| 模型 | 公网提供 `Qwen3.7-plus` API 地址、模型 ID 和密钥；私网提供 Token API 地址、模型 ID、鉴权与 GPU / 显存方案 |
| 授权 | 首次登录后的机器码，以及厂商签发的 `license.lic` |
| 部署账号 | 一个有 Docker 权限的 Linux 用户，用于解压和执行 `deploy.sh` |

## 部署前确认清单

按顺序确认，确认一项再做下一项。

1. 明确部署方案：私有化局域网模型，还是公网模型。
2. 按方案准备服务器：GIS Agent、数据库、Token 服务器（私网模型需要）。
3. 在 GIS Agent 业务服务器执行 `docker ps` 和 `docker compose version`。
4. 确认 GIS Agent 能访问数据库端口。
5. 使用局域网模型时，确认 GPUStack worker 为 `READY`、目标模型为 `RUNNING`。
6. 使用局域网模型时，从 GIS Agent 运行环境验证 `/v1/models` 和 `/v1/chat/completions`，确认模型 ID 和鉴权有效。
7. 使用公网模型时，确认 GIS Agent 能访问模型 API 的 `443` 端口。
8. 上传离线包，按"数据库 → 局域网模型（如有）→ GIS Agent"的顺序部署。
9. 用浏览器访问 `http://<GIS-Agent-IP>:17076/`，登录后完成授权。

清单全绿只代表"环境具备了"，不代表"能对话"。验收判据见[实施与运维要点](https://gisagent.mapgis.com/docs/offline-deploy-ops.md)的部署后验收一节；信创现场还要再叠加对应基线的闸门，见[x86 + 银河麒麟 V11](https://gisagent.mapgis.com/docs/offline-deploy-kylin.md) 或[龙芯 + 统信 UOS](https://gisagent.mapgis.com/docs/offline-deploy-loongarch.md)。

## 与技能影响范围的关系

本页是**机器与网络层面**的准备；[离线部署：技能影响范围](https://gisagent.mapgis.com/docs/offline-deploy.md)是**技能与出图层面**的准备，按前端库、底图瓦片、注记字体、要素数据四个环节把 49 个技能分成 L1–L6。两个口径不同但方向一致：

* 手册的联网能力矩阵针对 `agent-*` 运行面，结论是纯局域网下四条 Agent 默认不可用，必须改指向内网兼容端点；
* 技能影响页针对制图产出，结论是 42 个技能需要本地化底图、字体或数据源，只有 7 个可直接离线出图。

落地顺序建议：先按本页把三台机器和网络打通，再按技能影响页处置 L1（前端库），然后依次处理 L2 底图、L3 注记字体、L4 数据与 L5 自有服务地址。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.