GIS团队代码管理混乱？手把手教你配置GitLab私有仓库（附：环境部署清单）

wowwwai GIS研习社 · 工具流程与项目排障

《GIS团队代码管理混乱？手把手教你配置GitLab私有仓库（附：环境部署清单）》这篇文章面向正在维护 ArcPy 脚本、QGIS 插件、WebGIS 前端、PostGIS SQL 和数据处理流程的 GIS 团队，目标是解决一个很常见的问题：代码分散在个人电脑、微信群、网盘和临时压缩包里，版本说不清、责任追不清、上线容易出错。

引言：为什么 GIS 团队需要 GitLab 私有仓库

很多 GIS 项目不是单纯的软件开发项目，而是代码、空间数据、地图服务配置、数据库脚本和制图模板混在一起。一个典型团队里，可能同时存在这些内容：

• ArcPy 批处理脚本，例如批量投影转换、字段清洗、空间分析模型。
• QGIS 项目文件、插件代码、样式文件和处理模型。
• WebGIS 前端代码，例如 Leaflet、OpenLayers、Cesium 项目。
• PostGIS 建表语句、空间索引脚本、视图和函数。
• GeoServer、MapServer、Nginx、Docker Compose 等部署配置。
• 项目文档、接口说明、部署说明和数据更新记录。

如果这些内容没有统一的代码管理方式，最容易出现“我电脑上是最新版本”“昨天发给你的压缩包不是最终版”“生产库 SQL 谁改过不知道”这类问题。GitLab 私有仓库适合 GIS 团队内部部署，因为它不仅能管理 Git 代码，还能做权限控制、代码评审、Issue 跟踪、CI/CD 自动化和项目文档沉淀。

背景：GIS 团队代码管理混乱通常混乱在哪里

在 GIS 项目中，代码管理混乱往往不是因为团队不知道 Git，而是因为没有把 GIS 工作流纳入版本管理规则。下面这些场景非常常见。

1. 脚本版本靠文件名区分

例如同一个 ArcPy 脚本目录下出现：

clip_data.py
clip_data_new.py
clip_data_final.py
clip_data_final_202405.py
clip_data_final_领导确认版.py

这种命名方式短期看很直观，长期会让团队无法判断哪个脚本正在被生产环境使用，也无法追踪某一次字段处理规则是谁修改的。

2. WebGIS 前端和地图服务配置分离

前端代码在一个人电脑里，GeoServer 图层发布参数在另一台服务器上，Nginx 反向代理配置又只存在运维机器里。等到地图打不开、瓦片请求 404、坐标偏移时，很难快速定位问题是代码、服务、数据还是配置导致的。

3. PostGIS SQL 没有版本记录

空间数据库里的表结构、索引、视图、函数如果只在数据库中直接修改，而没有保存到仓库，后续迁移环境或回滚问题会非常痛苦。

例如某个项目中临时执行了：

CREATE INDEX idx_parcel_geom ON parcel USING GIST (geom);

如果这条 SQL 没有进入仓库，测试环境和生产环境就可能出现性能差异，团队也不知道某个查询为什么在一台机器上快、另一台机器上慢。

4. 空间数据和代码边界不清

GitLab 私有仓库适合管理代码、配置、小型样例数据和文档，但不适合直接管理大量影像、倾斜摄影、点云、瓦片缓存或完整生产数据库备份。很多 GIS 团队一开始把所有文件都塞进 Git 仓库，结果仓库很快膨胀到几个 GB，克隆和拉取都非常慢。

原理：GitLab 私有仓库在 GIS 项目中到底管什么

Git 是分布式版本控制工具，负责记录每一次代码变化。GitLab 是基于 Git 的协作平台，提供网页界面、权限管理、Merge Request、Issue、CI/CD 等功能。对于 GIS 团队来说，可以把 GitLab 私有仓库理解为“项目代码与工程配置的可信来源”。

建议纳入 GitLab 私有仓库的内容包括：

• Python GIS 脚本：ArcPy、GeoPandas、Rasterio、GDAL 脚本。
• WebGIS 代码：Vue、React、Leaflet、OpenLayers、Cesium 项目。
• 数据库脚本：PostGIS 建表、索引、视图、函数、迁移 SQL。
• 服务配置：Docker Compose、GeoServer 配置说明、Nginx 配置模板。
• QGIS 相关文件：插件源码、处理模型、小型样式文件、项目模板。
• 文档：README、部署手册、字段说明、接口说明、数据处理流程。
• 小型样例数据：用于测试的 GeoJSON、CSV、少量 Shapefile 样例。

不建议直接纳入普通 Git 仓库的内容包括：

• 大体量遥感影像，例如 GeoTIFF、IMG、JP2。
• 大范围矢量全量数据，例如全国级 Shapefile、FileGDB、GeoPackage。
• 点云、三维模型、倾斜摄影、瓦片缓存。
• 数据库完整备份文件。
• 包含账号、密码、Token、数据库连接串的真实配置文件。

如果确实需要管理大文件，可以评估 Git LFS、对象存储、NAS 文件服务器或制品仓库，但不要把 GitLab 私有仓库当成网盘使用。

步骤：手把手配置 GitLab 私有仓库

步骤 1：准备 GitLab 部署环境清单

在部署前先准备环境清单，避免装到一半才发现域名、端口、磁盘或邮件服务不完整。

项目	建议配置	GIS 团队注意点
服务器	Linux 服务器，推荐 Ubuntu Server 或 Rocky Linux	建议独立于 GeoServer、PostGIS 生产服务，避免互相影响
CPU	至少 2 核，团队人数多时提高配置	CI/CD 编译 WebGIS 项目会消耗 CPU
内存	至少 4GB，推荐 8GB 起步	GitLab 服务较重，小内存机器容易卡顿
磁盘	建议 SSD，预留足够仓库和备份空间	不要把影像、点云、瓦片缓存直接提交到仓库
域名	如 gitlab.company.local 或 gitlab.example.com	内网团队可使用内网 DNS 或 hosts 临时解析
端口	HTTP/HTTPS、SSH	确认防火墙、安全组和内网访问策略
邮件	SMTP 服务	用于用户邀请、密码找回、Merge Request 通知
备份	定时备份仓库、配置和数据库	建议备份到独立磁盘或独立服务器

步骤 2：安装 GitLab

下面以 Linux 服务器部署 GitLab 社区版为例。实际安装命令会随发行版和 GitLab 官方仓库变化，请以 GitLab 官方文档为准。这里重点说明 GIS 团队部署时必须关注的配置项。

安装前先设置主机名和访问地址，例如：

sudo hostnamectl set-hostname gitlab-gis

如果使用包管理方式安装，核心配置通常集中在：

/etc/gitlab/gitlab.rb

需要重点设置外部访问地址：

external_url 'http://gitlab.example.com'

如果已经有 HTTPS 证书，建议直接使用 HTTPS：

external_url 'https://gitlab.example.com'

修改配置后执行重新配置：

sudo gitlab-ctl reconfigure

然后检查服务状态：

sudo gitlab-ctl status

如果访问页面失败，优先检查以下内容：

• 域名是否解析到正确服务器。
• 服务器防火墙是否放行 HTTP、HTTPS 或 SSH 端口。
• GitLab 服务是否全部处于运行状态。
• 反向代理是否与 GitLab 自带 Nginx 端口冲突。

步骤 3：创建 GIS 团队组织结构

GitLab 中建议用 Group 管团队，用 Project 管具体仓库。GIS 团队可以按业务线、项目或技术方向建立 Group。

一种实用结构如下：

gis-team
├── webgis
│   ├── city-map-frontend
│   └── cesium-3d-platform
├── python-gis
│   ├── arcpy-batch-tools
│   └── geopandas-data-cleaning
├── postgis
│   ├── spatial-db-schema
│   └── sql-performance-tuning
├── qgis
│   ├── qgis-plugin-tools
│   └── qgis-project-templates
└── deployment
    ├── geoserver-config
    └── nginx-docker-compose

不要把所有代码都放进一个“大杂烩仓库”。一个仓库最好对应一个相对清晰的工程边界，例如一个 WebGIS 前端、一个 ArcPy 工具集、一个 PostGIS 数据库结构项目。

步骤 4：配置成员权限

GitLab 权限不要一律给最高权限。GIS 团队通常可以这样分配：

角色	适合人员	建议权限
Owner	技术负责人、平台管理员	管理 Group、成员、关键设置
Maintainer	项目负责人、高级工程师	管理仓库、合并代码、配置 CI/CD
Developer	GIS 工程师、前端开发、数据处理人员	提交分支、发起 Merge Request
Reporter	测试、项目经理、业务人员	查看代码、Issue、文档和构建结果
Guest	外部协作方	有限查看权限

关键原则是：生产分支不要允许所有人直接推送。对于 main、master、release 这类分支，应开启保护分支，只允许 Maintainer 合并。

步骤 5：初始化 GIS 项目仓库

以一个 ArcPy 批处理工具仓库为例，推荐目录结构如下：

arcpy-batch-tools
├── README.md
├── requirements.txt
├── .gitignore
├── config
│   └── config.example.ini
├── scripts
│   ├── batch_project.py
│   └── clip_by_boundary.py
├── sql
│   └── create_index.sql
├── sample_data
│   └── README.md
├── docs
│   └── workflow.md
└── tests
    └── test_paths.py

这里有几个细节很重要：

• config.example.ini 只放示例配置，不放真实数据库密码。
• sample_data 只放小型样例数据或说明，不放完整生产数据。
• README.md 写清楚运行环境、输入数据、输出结果和常见错误。
• sql 目录保存与空间数据库相关的建表和索引脚本。
• .gitignore 排除临时文件、缓存、日志、大数据和本地环境文件。

步骤 6：为 GIS 项目配置 .gitignore

GIS 项目常见的临时文件和大文件较多，必须认真配置 .gitignore。下面是一个可参考的模板：

# Python
__pycache__/
*.pyc
.venv/
venv/
.env
.env.*

# Logs
*.log
logs/

# IDE
.vscode/
.idea/

# QGIS temporary files
*.qgz~
*.qgs~
*.aux.xml

# ArcGIS temporary files
*.lock
*.sr.lock
*.gdb.lock
*.freelist

# Large GIS data
*.tif
*.tiff
*.img
*.jp2
*.las
*.laz
*.mbtiles
*.gpkg
*.gdb/
*.sde

# Shapefile sample data rule
# 如果确实要提交小型样例 Shapefile，请单独放到 sample_data 并谨慎确认
*.shp
*.shx
*.dbf
*.prj
*.cpg

# Local config
config/*.ini
!config/config.example.ini

需要注意，Shapefile 是多文件格式，不能只提交 .shp。对于小型教学或测试数据，更推荐使用 GeoJSON、CSV 或小型 GeoPackage；但如果 GeoPackage 变大，也不应进入普通 Git 仓库。

步骤 7：建立分支管理规则

GIS 团队可以从简单分支模型开始，不必一上来就设计过重流程。

• main：稳定分支，对应可交付或生产版本。
• dev：日常集成分支，用于合并正在开发的功能。
• feature/xxx：具体功能分支，例如 feature/postgis-index。
• fix/xxx：问题修复分支，例如 fix/projection-error。
• release/xxx：发布准备分支，例如 release/v1.2.0。

一个常见流程是：

1. 工程师从 dev 拉出 feature 分支。
2. 在 feature 分支完成代码和文档修改。
3. 提交到 GitLab，发起 Merge Request。
4. 负责人检查代码、运行结果和影响范围。
5. 通过后合并到 dev。
6. 测试稳定后再合并到 main 或 release 分支。

对于 PostGIS SQL、数据处理脚本、地图服务配置这类会影响生产环境的内容，强烈建议必须通过 Merge Request 合并，不能直接在服务器上手改。

步骤 8：配置 Merge Request 审查模板

GIS 项目的代码审查不仅要看语法，还要看空间数据处理结果是否可靠。可以在仓库中增加 Merge Request 模板，例如：

.gitlab/merge_request_templates/gis_review.md

模板内容可参考：

## 修改内容
- 

## 涉及模块
- [ ] ArcPy / Python GIS 脚本
- [ ] WebGIS 前端
- [ ] PostGIS SQL
- [ ] QGIS 项目或插件
- [ ] 部署配置

## GIS 结果检查
- [ ] 坐标系已确认
- [ ] 面积、长度或空间关系结果已抽样验证
- [ ] 输出字段已检查
- [ ] 样例数据可复现
- [ ] 不包含生产数据或敏感信息

## 风险说明
- 

## 回滚方式
- 

这个模板可以让团队在合并前检查坐标系、字段、空间索引、数据范围和回滚方案，减少“代码能跑但结果不对”的问题。

步骤 9：配置基础 CI/CD 检查

如果团队已经具备自动化条件，可以给 GitLab 私有仓库增加基础 CI/CD。对于 GIS 项目，CI/CD 不一定一开始就做完整部署，先做“能否安装依赖、能否通过基础检查、是否误提交敏感文件”就很有价值。

一个 Python GIS 项目的 .gitlab-ci.yml 示例：

stages:
  - check

python_check:
  stage: check
  image: python:3.11
  script:
    - python --version
    - pip install -r requirements.txt
    - python -m compileall scripts
  only:
    - merge_requests
    - dev
    - main

对于 WebGIS 前端项目，可以增加依赖安装和构建检查：

stages:
  - build

webgis_build:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build
  only:
    - merge_requests
    - dev
    - main

如果项目依赖 ArcGIS Pro 的 ArcPy，需要注意 ArcPy 不能简单放进普通 Linux 容器中运行。此时可以把 CI/CD 设计为代码静态检查、文档检查、配置检查，或者使用具备 ArcGIS Pro 环境的 Windows Runner。

常见坑：配置 GitLab 私有仓库时最容易踩的坑

坑 1：把 GitLab 当作 GIS 数据网盘

GitLab 私有仓库不是影像库、瓦片库或空间数据备份库。把大量 GeoTIFF、FileGDB、LAS、MBTiles 放进仓库，会导致克隆慢、备份慢、迁移困难，甚至让 GitLab 存储迅速耗尽。

建议做法是：

• 代码和配置进入 GitLab。
• 大数据进入对象存储、NAS、数据库或专用数据管理平台。
• 仓库中保存数据路径说明、数据字典和小型样例数据。

坑 2：真实账号密码被提交

GIS 项目经常包含数据库连接、GeoServer 管理账号、对象存储密钥、第三方地图服务 Token。不要把这些内容写死在代码中。

建议做法：

• 提交 config.example.ini，而不是 config.ini。
• 使用环境变量读取敏感配置。
• 在 GitLab CI/CD Variables 中保存构建所需密钥。
• 定期检查仓库历史中是否误提交过密码。

坑 3：没有保护 main 分支

如果所有成员都可以直接推送 main 分支，GitLab 私有仓库只是换了一个更漂亮的共享文件夹，无法真正控制质量。

建议至少设置：

• main 分支禁止 Developer 直接 push。
• 合并 main 必须走 Merge Request。
• 关键仓库至少一人 Review。
• 发布版本使用 Tag，例如 v1.0.0、v1.1.0。

坑 4：只管理代码，不管理数据库脚本

很多 GIS 问题最终出在 PostGIS 表结构、空间索引、SRID、视图和函数上。如果数据库变更没有进入 GitLab，代码版本再清楚也不完整。

建议为数据库建立独立目录或仓库，保存：

• 建表 SQL。
• 空间索引 SQL。
• 视图和函数 SQL。
• 迁移脚本。
• 数据字典和字段说明。

坑 5：没有写 README

README 是团队协作的入口。一个 GIS 仓库至少要说明：

• 项目用途。
• 运行环境。
• 依赖安装方式。
• 输入数据要求。
• 输出结果说明。
• 坐标系要求。
• 常见错误和排查方法。

方法比较：GitLab 私有仓库、GitHub、Gitee 和文件共享怎么选

方案	适合场景	优点	限制
GitLab 私有仓库	内网团队、涉密项目、需要权限和 CI/CD 的 GIS 项目	可私有部署，权限细，适合团队流程	需要服务器维护和备份
GitHub 私有仓库	互联网协作、开源生态、非涉密项目	生态成熟，协作体验好	部分团队受网络、合规或数据安全限制
Gitee 私有仓库	国内网络环境、轻量团队协作	访问方便，上手较快	复杂内网部署和自定义流程可能不如自建灵活
共享文件夹或网盘	临时传文件、非代码资料共享	简单直接	缺少版本、分支、审查、回滚和责任追踪

如果团队只是临时共享少量文档，网盘足够；如果团队要长期维护 WebGIS 平台、ArcPy 工具、PostGIS 脚本和部署配置，GitLab 私有仓库更适合。

检查清单：GIS 团队 GitLab 私有仓库部署前后必查

部署前检查

• 服务器 CPU、内存、磁盘是否满足团队规模。
• 是否规划好 GitLab 域名或内网访问地址。
• HTTP、HTTPS、SSH 端口是否放行。
• 是否有 SMTP 邮件服务。
• 是否规划仓库备份目录和异地备份策略。
• 是否明确哪些数据不能进入 Git 仓库。

仓库初始化检查

• 是否创建 README.md。
• 是否创建 .gitignore。
• 是否提供 config.example.ini。
• 是否排除真实密码、Token 和数据库连接串。
• 是否把大体量 GIS 数据排除在仓库外。
• 是否保存必要的 PostGIS SQL 和部署配置模板。

协作流程检查

• main 分支是否已保护。
• 是否要求通过 Merge Request 合并。
• 是否设置成员权限，而不是所有人 Maintainer。
• 是否约定 feature、fix、release 分支命名。
• 是否建立代码审查模板。
• 是否使用 Tag 标记发布版本。

GIS 结果质量检查

• 坐标系和 SRID 是否在文档中写明。
• 面积、长度、叠加分析等结果是否有抽样验证。
• PostGIS 空间索引是否有对应 SQL。
• WebGIS 坐标转换、底图坐标系和服务坐标系是否一致。
• 样例数据是否能复现核心流程。
• 生产数据是否没有被误提交。

FAQ：GIS 团队配置 GitLab 私有仓库常见问题

1. GitLab 私有仓库可以直接管理 Shapefile 吗？

技术上可以，但不建议大量管理。Shapefile 是多文件格式，至少包含 .shp、.shx、.dbf、.prj 等文件，漏掉任何一个都可能导致数据异常。建议只提交小型样例数据，并在 README 中写清楚用途。完整生产数据应放在数据库、对象存储或文件服务器中。

2. QGIS 项目文件可以放进 GitLab 吗？

可以。QGIS 的 .qgz 或 .qgs 项目文件、样式文件、处理模型可以进入仓库。但要注意项目文件中是否包含本机绝对路径，例如 D 盘路径或个人目录。团队协作时建议使用相对路径，并写清楚数据目录约定。

3. ArcPy 脚本能不能通过 GitLab CI 自动测试？

可以，但要看运行环境。ArcPy 依赖 ArcGIS Pro 或 ArcGIS Server 的 Python 环境，通常不能直接在普通 Linux Docker 镜像中运行。如果要自动测试 ArcPy，建议配置 Windows GitLab Runner，并确保机器上安装了合法可用的 ArcGIS Pro 环境。

4. PostGIS 数据库结构应该放在哪个仓库？

如果项目较小，可以放在同一个项目仓库的 sql 目录下。如果多个应用共用一套空间数据库，建议建立独立的 postgis-schema 仓库，统一管理建表、索引、视图、函数和迁移脚本。

5. GitLab 私有仓库和 GeoServer 配置怎么配合？

GeoServer 的完整运行目录不建议随意提交，但可以把图层发布说明、工作区命名规范、样式 SLD、Nginx 反向代理模板、Docker Compose 文件和部署文档放进 GitLab。这样即使服务器迁移，也能按文档恢复服务结构。

6. 已经把大文件提交进 GitLab 仓库怎么办？

先停止继续提交大文件，然后把文件移出仓库并更新 .gitignore。需要注意，普通删除只会在最新版本中删除文件，历史记录中仍可能存在大文件。如果仓库已经严重膨胀，需要评估清理 Git 历史记录，并在操作前完整备份仓库。

7. 小团队有没有必要部署 GitLab？

如果只是一个人写临时脚本，本地 Git 或托管私有仓库即可。如果有多人协作、项目周期较长、涉及生产部署或需要保留审查记录，GitLab 私有仓库就很值得配置。GIS 项目越依赖脚本、数据库和地图服务配置，越需要规范的版本管理。

结论：先把 GitLab 私有仓库用起来，再逐步完善流程

GIS 团队代码管理混乱，表面看是文件太多、版本太乱，根本原因是没有把脚本、数据库、WebGIS、地图服务配置和文档放进统一协作流程。GitLab 私有仓库可以帮助团队建立一个可信的项目入口，让每一次修改都有记录、每一次合并可审查、每一次发布可回滚。

实际落地时，不建议一开始追求复杂流程。先完成三件事：部署可访问的 GitLab，建立清晰的仓库结构，保护 main 分支并使用 Merge Request。随后再逐步加入 CI/CD、审查模板、备份策略和数据管理规范。

对 GIS 团队来说，GitLab 私有仓库不是单纯的代码仓库，而是项目工程化的基础设施。只要把边界划清楚：代码、配置、SQL、文档进仓库，大体量空间数据走专门的数据管理通道，团队的协作效率和交付可靠性会明显提升。