部署常见问题

以下命令都在部署目录中执行；安装时用了 --project <名称> 的，docker compose 命令加 -p <名称>。

安装脚本中止

安装脚本在以下情况中止（退出码 1，不启动任何容器）：

提示	原因与处理
需要 Docker 20.10 及以上，当前为 {版本}	未安装 Docker、Docker 未启动或当前用户无权限（版本显示为「未安装」「未知」），或版本过旧
需要 Docker Compose v2（docker compose 命令）、需要 Docker Compose 2.20 及以上，当前为 {版本}	只有旧的 docker-compose，或 Compose 过旧
端口 {端口} 已被占用，请用 {参数} 指定其他端口或释放该端口	见下文「端口已被占用」；此时不会写 .env
无法交互询问访问地址：请用 --host 指定对外 IP 或域名	没有终端且 .env 中还没有访问地址
访问地址只能是 IP 或域名（不带 http:// 与路径）：{值}	--host 或输入的地址带了协议或路径
检测到已有数据卷，但 .env 中缺少 {变量名}：请从备份的 .env 恢复该值后重试	数据卷已存在而 .env 缺少主密钥或数据库密码。重新生成会导致已加密的数据无法解密、连不上数据库，请从备份恢复
本机没有镜像 {仓库}:{版本}：请使用离线包（--offline），或在 .env 中设置 GEOBRIDGE_IMAGE_REPO 指向已推送的仓库	在线安装而本机没有应用镜像，见在线安装
无法在 8 秒内连接镜像仓库 {仓库}（本机没有镜像 {镜像}，需要从该仓库拉取）。…	在线安装而镜像仓库不通（常见于中国大陆访问 Docker Hub）：改用离线包、配置镜像加速器，或确认网络可用时加 --skip-registry-check。此时 .env 已生成
离线包中没有镜像文件：…/images/*.tar、离线包中没有镜像 {仓库}:{版本}	用了 --offline 但 images/ 为空，或 .env 的 GEOBRIDGE_VERSION 与离线包的版本不符
服务在 5 分钟内未就绪：{服务名, …}。查看日志：…	已启动但未全部健康，见下文「健康检查超时」

内存少于 8 GB 只给出警告 Docker 可用内存 {n} GB，少于建议的 8 GB，服务可能无法稳定运行，不中止。

端口已被占用

用 --port、--app-port 换一个端口重新运行，或停掉占用端口的程序（用 ss -ltnp | grep :80 或 lsof -i :80 查看）。已安装后要改端口：./install.sh --port <新端口>（同时更新访问地址）。

健康检查超时

提示 服务在 5 分钟内未就绪：{服务名, …}。查看日志：docker compose -p {项目} logs {服务名} 时，按服务查看：

• postgres、redis、minio：看对应日志，常见原因是磁盘满或卷权限问题。
• app：docker compose logs app。常见原因：
  • 连不上数据库：.env 中的数据库密码与首次建库时不同；
  • RSA 私钥无法用当前主密钥解密：GEOBRIDGE_SECRET_KEY 与加密时不同，换回原来的值；
  • 内存不足被系统终止：docker inspect <容器> --format '{{.State.OOMKilled}}' 为 true 时调大内存，见内存。
• worker：在 app 健康之后才启动，app 未就绪时它也不会就绪。
• nginx：docker compose logs nginx，多为修改过的配置文件有语法错误。

性能较低的机器（或 Apple silicon 上的仿真）上，app 首次启动可能超过 5 分钟。服务会继续启动，稍后用 docker compose ps 查看状态，或重新运行 install.sh。

忘记管理员密码

平台没有图形界面的找回方式。请按离线包中安装手册 INSTALL.md「常见问题」一节的命令，在服务器上为 admin 生成新密码（新密码须为 8–64 位，至少包含字母、数字、符号中的两类）。

登录失败次数过多被锁定

同一账号 15 分钟内失败 5 次，或同一 IP 地址 15 分钟内失败 30 次，会被锁定 15 分钟，期间提示「登录失败次数过多，请 15 分钟后再试」，到时自动解除。需要立即解除时，按 INSTALL.md「常见问题」一节清除锁定记录。

如果所有人都被同时锁定，通常是平台前面的反向代理没有正确传递客户端地址，见 HTTPS 与反向代理。

数据目录权限

app 与 worker 以 uid 10001（用户 geobridge）运行。Docker 命名卷首次挂载时自动归它所有；若把应用数据目录 /var/lib/geobridge 改成宿主目录的绑定挂载，或沿用以 root 身份写过的目录，启动会因 Permission denied 反复重启。先执行 chown -R 10001:10001 <目录>。

外部客户端加载不了地图，控制台却正常

多半是访问地址 GEOBRIDGE_WEB_BASE_URL 不是外部用户实际使用的地址：矢量切片、样式与 OGC 服务（WMS、WFS、WMTS、WCS、TMS、OGC API）文档中的地址都由它生成。按修改访问地址改正后执行 docker compose up -d。

查看与进入容器

docker compose ps                 # 各服务状态
docker compose logs -f app        # 跟踪应用日志
docker compose exec postgres psql -U postgres -d geobridge   # 进入数据库

对象存储

服务名为 minio，使用 S3 兼容的对象存储镜像，不发布端口。需要直接查看存储的对象时：

docker compose run --rm objsync lsf -R store:geobridge-datastore