安装

GeoBridge 以 Docker Compose 部署在一台服务器上。本页说明环境要求、安装方式、安装脚本的参数、首次登录与常用配置。只想尽快跑起来，可以先看快速开始（本地部署）。

组成

一台服务器上运行六个容器：

服务	作用
`nginx`	唯一对外的入口（默认端口 80）
`app`	主服务：控制台、地图编辑器、REST 与 OGC 服务。只发布在本机 `127.0.0.1:9086`
`worker`	数据处理节点（数据转换、切片等），不发布端口
`postgres`	数据库（PostgreSQL + PostGIS）
`redis`	缓存与会话
`minio`	S3 兼容的对象存储，保存上传的文件与处理结果

数据保存在四个 Docker 命名卷中（数据库、Redis、对象存储与应用数据），卷名以项目名（默认 geobridge）为前缀。

部署目录（离线包解压后的 geobridge-<版本>/）包含 compose.yml、install.sh、backup.sh、restore.sh、nginx/geobridge.conf、.env.example 与安装手册 INSTALL.md，离线包另有镜像文件 images/。以下命令都在部署目录中执行。

环境要求

硬件：生产环境单机建议 8 核 CPU、32 GB 内存起步；试用时 Docker 可用内存不少于 8 GB（不足时安装脚本给出警告但继续）。磁盘：镜像约 3 GB，另按数据量预留（数据都在 Docker 的数据目录下）。
系统：Linux（x86_64）。也可以在 macOS 上试用：应用镜像只有 linux/amd64 版本，Apple silicon 上以仿真方式运行，只适合试用。需要 bash 与 openssl。
Docker：20.10 及以上；Docker Compose v2（docker compose 命令）2.20 及以上。运行脚本的用户能执行 docker（root、docker 组或 Docker Desktop）。
端口：对外端口（默认 80）与本机应用端口（默认 9086）空闲。云服务器的安全组只需放行对外端口（启用 HTTPS 时为 443）。

离线安装（推荐）

从下载页获取离线包 geobridge-0.1.0-linux-amd64.tar.gz 与校验文件，复制到服务器后核对、解压并安装：

bash

sha256sum -c geobridge-0.1.0-linux-amd64.tar.gz.sha256
tar xzf geobridge-0.1.0-linux-amd64.tar.gz
cd geobridge-0.1.0
./install.sh --offline --host <对外 IP 或域名>

--offline 从离线包加载全部镜像，启动时不拉取任何镜像，服务器不需要访问外网。中国大陆的服务器（含阿里云 ECS 等）推荐用离线包：Docker Hub 在大陆无法访问或很不稳定。

在线安装

应用镜像目前没有发布到公共镜像仓库，在线安装要求下列之一，否则安装脚本中止并提示：

本机已有应用镜像（如另行 docker load 过）；
镜像已推送到你的私有仓库：安装前在部署目录新建 .env，只写一行 GEOBRIDGE_IMAGE_REPO=<完整仓库名>（如 registry.example.com/geobridge/mapserver），并在服务器上 docker login 该仓库。

其余镜像（PostGIS、Redis、nginx 等）从 Docker Hub 拉取，其中部分按摘要固定版本。

bash

./install.sh --host <对外 IP 或域名>

安装脚本在启动前检查镜像仓库能否访问：需要拉取的镜像所在仓库 8 秒内没有响应时中止，并建议改用离线包。Docker 经代理拉取而本机直连不通时，加 --skip-registry-check。

中国大陆必须在线安装时，任选其一：

镜像加速器：在 /etc/docker/daemon.json 中配置 "registry-mirrors": ["https://<加速器地址>"]，systemctl restart docker 后再安装。加速器必须能按摘要提供被固定的镜像，拉取失败时换加速器或改用离线包。不要把 compose.yml 中的 nginx 改成浮动标签，旧版 nginx 不支持配置中用到的功能，会启动失败。
私有仓库：在能访问 Docker Hub 的机器上拉取全部镜像（docker compose --profile tools config --images 列出），推送到私有仓库，再在 .env 中写 GEOBRIDGE_IMAGE_REPO、GEOBRIDGE_NGINX_IMAGE、GEOBRIDGE_OBJECT_STORE_IMAGE、GEOBRIDGE_OBJSYNC_IMAGE 的完整引用（建议保留 @sha256: 摘要）；PostGIS、Redis 两个镜像在 compose.yml 中改为私有仓库的地址。

`install.sh` 参数

参数	默认	说明
`--host <主机>`	交互询问	对外访问的 IP 或域名，用于生成对外访问地址。云服务器填公网 IP 或域名（本机检测到的通常是私网地址）。在没有终端的环境（脚本、cloud-init）中运行时必须给出。`.env` 中已有访问地址时可省略
`--port <端口>`	`.env` 中的值，没有为 80	nginx 对外端口；给出时写回 `.env`，访问地址随之更新
`--app-port <端口>`	`.env` 中的值，没有为 9086	应用端口，只发布在 `127.0.0.1`，供本机排查
`--offline`	否	从离线包加载镜像，启动时不拉取
`--skip-registry-check`	否	在线安装时不检查镜像仓库能否访问
`--project <名称>`	`geobridge`	Compose 项目名，也是数据卷名的前缀。同一台机器装多套时用不同的项目名与端口

安装脚本依次：检查环境 → 检查端口 → 生成或补全 .env → 加载镜像（离线）或检查镜像仓库（在线）→ docker compose up -d → 等待六个服务全部健康（最长 5 分钟）→ 打印访问地址与初始密码。

可以重复运行：已有 .env 时只补缺失的项，已有的值不变；例外是给出 --port、--app-port、--host 时会改写对应的值。安装脚本写入的访问地址随端口与主机自动更新；你手工改过的访问地址不会被覆盖，只打印提示。
端口被占用时安装中止，且不写 .env。
数据卷已存在而 .env 缺少 GEOBRIDGE_SECRET_KEY 或 GEOBRIDGE_DB_PASSWORD 时安装中止：重新生成会导致已加密的数据无法解密、连不上已初始化的数据库。请从备份的 .env 恢复这两项后重试。
中止时的各种提示与处理方法见部署常见问题。

首次登录

安装结束时打印：

GeoBridge 已启动
访问地址：http://<主机>[:<端口>]/geobridge-mapserver/console/
管理员账号：admin
初始密码：<16 位随机密码>
首次登录后请立即修改密码。
请妥善保存 <部署目录>/.env：其中的 GEOBRIDGE_SECRET_KEY 不可更换，丢失后已加密的数据无法解密。

浏览器打开访问地址，用 admin 与初始密码登录（有图形验证码），登录后在个人资料中修改密码。访问 http://<主机>/ 会跳到控制台。
初始密码保存在 .env 的 GEOBRIDGE_ADMIN_INITIAL_PASSWORD，只在还没有管理员时用于创建 admin；之后修改这一项不会改变管理员密码。重复运行安装脚本时不再打印密码。
平台地址：本地部署的平台地址为 http://<主机>[:<端口>]/geobridge-mapserver。在 JS SDK 的 baseUrl、在线沙箱的「平台地址」中填这个地址。
健康检查：curl http://<主机>/geobridge-mapserver/health 返回 {"status":"UP","version":"0.1.0"}；数据库不可用时返回 503 与 "status":"DOWN"。该地址不需要登录。
没有有效许可证时，平台以预览版运行（仅限评估，不得商用），日志中有一条相应的警告，不影响使用。

`.env` 变量

.env 与 compose.yml 在同一目录，权限 600，含全部密钥。修改后在部署目录执行 docker compose up -d 生效（只重建受影响的容器）。完整清单与注释见部署目录的 .env.example。常需要关注的变量：

变量	默认	说明
`GEOBRIDGE_VERSION`	`0.1.0`	应用版本（升级时修改）
`GEOBRIDGE_HTTP_PORT`	`80`	nginx 对外端口
`GEOBRIDGE_APP_PORT`	`9086`	应用端口（只在 `127.0.0.1`）
`GEOBRIDGE_WEB_BASE_URL`	安装脚本生成	对外访问地址，见修改访问地址
`GEOBRIDGE_ADMIN_INITIAL_PASSWORD`	安装脚本生成	初始管理员密码，只在还没有管理员时使用
`GEOBRIDGE_DB_PASSWORD`	安装脚本生成	数据库密码，只在首次建库时生效，之后不要修改
`GEOBRIDGE_SECRET_KEY`	安装脚本生成	主密钥。不可更换，丢失后已加密的数据无法解密，请与数据库备份分开保管
`GEOBRIDGE_JWT_SECRET`	安装脚本生成	登录令牌的签名密钥，更换后已登录的用户需要重新登录
`GEOBRIDGE_OUTBOUND_BLOCK_PRIVATE`	`true`	数据源不允许连接内网地址。在线系统必须为 `true`，见 HTTPS 与反向代理
`GEOBRIDGE_OUTBOUND_ALLOW`	空	上一项的例外：逗号分隔的 CIDR、IP 与主机名，如云数据库的内网地址
`GEOBRIDGE_SERVER_DATA_ROOTS`	空	「服务器目录」数据源可浏览的目录。在线系统不要配置
`GEOBRIDGE_TILE_CACHE_ENABLED`	`true`	瓦片运行时缓存；`false` 时每次请求都现场生成
`GEOBRIDGE_CAPTCHA_ENABLED`	`true`	登录验证码，只在测试环境关闭
`GEOBRIDGE_LICENSE_REQUIRED`	`false`	为 `true` 时没有有效许可证则启动失败
`GEOBRIDGE_FEATURE_3D`、`GEOBRIDGE_FEATURE_AI`	`false`	实验功能开关，见功能开关
`GEOBRIDGE_APP_MEMORY`、`GEOBRIDGE_WORKER_MEMORY` 等	见下文	内存，见内存

上传大小、邮件、地图服务商 Key 等其余变量的含义见 .env.example 中的注释。

安装时用了 --project <名称> 的，每条 docker compose 命令都加 -p <名称>（backup.sh、restore.sh 加 --project <名称>）。
手动执行 docker compose 时，shell 中导出的同名环境变量优先于 .env；install.sh、backup.sh、restore.sh 只用 .env。

修改访问地址

访问地址（GEOBRIDGE_WEB_BASE_URL）必须是外部用户实际使用的地址。地址不对时控制台仍能用，但发布的矢量切片、样式，以及 OGC 服务（WMS、WFS、WMTS、WCS、TMS、OGC API）文档中的地址都会指向错误的位置，外部客户端的地图加载失败。

只换主机或端口：重新运行 ./install.sh --host <新主机> 或 ./install.sh --port <新端口>。
改成域名、启用 HTTPS，或前面另有端口映射、负载均衡时，直接编辑 .env：
bash
```
# .env
GEOBRIDGE_WEB_BASE_URL=https://map.example.com/geobridge-mapserver
```
然后执行 docker compose up -d。

内存

容器	上限（变量，默认）	说明
app	`GEOBRIDGE_APP_MEMORY`，`4g`	Java 堆默认取上限的 70%；要固定堆大小时设 `GEOBRIDGE_APP_JAVA_OPTS=-Xmx3g`
worker	`GEOBRIDGE_WORKER_MEMORY`，`3g`	堆由 `GEOBRIDGE_WORKER_JAVA_OPTS` 设置（默认 `-Xmx768m`）；数据处理工具按 `GEOBRIDGE_WORKER_TOOL_MEMORY_MB`（默认 1800）调度任务

worker 的上限应满足：上限 ≈ 堆 + 工具内存预算 + 512 MB。超出容器上限时 worker 会被系统终止，任务重试后仍会失败。处理数 GB 的影像时按比例调大，例如：

bash

# .env
GEOBRIDGE_WORKER_MEMORY=10g
GEOBRIDGE_WORKER_JAVA_OPTS=-Xmx1536m
GEOBRIDGE_WORKER_TOOL_MEMORY_MB=8192

默认配置下 worker 日志中会有一条「处理节点内存预算 1800 MB 小于 8192 MB」的警告，表示大影像转换等重型任务一次只运行一个，属正常现象。

多节点

Compose 部署是单机形态。需要多个 app 节点时，各节点共用同一套 PostgreSQL、Redis 与对象存储，设置相同的 .env 密钥，由一台独立的 nginx 负载均衡，节点的 9086 端口只对 nginx 开放（防火墙或内网隔离）。nginx 的 upstream 改为列出各节点：

nginx

upstream geobridge_app {
    ip_hash;  # 可选：同一客户端固定到同一节点
    server 192.168.1.10:9086 max_fails=3 fail_timeout=30s;
    server 192.168.1.11:9086 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

其余与部署目录的 nginx/geobridge.conf 相同（去掉 resolver 以及 upstream 中的 zone、resolve）。多节点必须配置共用的 Redis，否则一个节点上的数据修改不会让其他节点的瓦片缓存失效。

下一步

HTTPS 与反向代理
升级与备份恢复
发布第一个服务：快速开始（在线）第 2 步起，在本地部署的控制台中同样适用。

安装 ​

组成 ​

环境要求 ​

离线安装（推荐） ​

在线安装 ​

install.sh 参数 ​

首次登录 ​

.env 变量 ​

修改访问地址 ​

内存 ​

多节点 ​

下一步 ​

安装

组成

环境要求

离线安装（推荐）

在线安装

`install.sh` 参数

首次登录

`.env` 变量

修改访问地址

内存

多节点

下一步