头程 GitLab 建仓清单

1. 建仓结论

头程项目创建一个 GitLab 仓库，不按服务拆成多个 Git 仓库。

原因：当前是一个 Maven Reactor 多模块工程，公共组件、平台 BOM、事件契约和 11 个可运行服务共享根父工程并统一构建。此时按服务拆仓会破坏父 POM、公共版本管理和现有流水线。服务仍然可以独立打包、独立镜像和独立部署，Git 仓库数量不等于微服务数量。

GitLab 创建参数：

字段	填写内容
项目名称	百悦头程平台
项目标识	`baiyue-firstleg`
项目描述	百悦物流国内头程微服务平台，包含统一登录、租户权限、订单、头程履约、国内仓储、文件、打印、审计、外部集成与跨区域事件桥。
可见性	私有
默认分支	`main`
使用 README 初始化	否，本地项目已有 README
Git 忽略模板	不选择，本地已有 `.gitignore`
许可证	不选择，内部商业项目

本地目录：D:\baiyue-firstleg。

2. 每个可运行服务的描述

以下 11 个模块都是独立运行服务，但属于同一个 GitLab 仓库。

模块	建议制品或镜像名	默认端口	中文描述
`gateway`	`firstleg-gateway`	9000	头程统一 API 入口，负责路由、跨域、统一鉴权入口、限流与 Swagger 聚合。
`auth`	`auth-service`	9100	统一认证服务，负责注册、登录、Access Token、Refresh Token、退出、修改密码和会话撤销。
`iam`	`iam-service`	9201	租户与权限服务，负责企业、成员、角色、菜单、按钮权限、数据隔离和企业资质审核。
`firstleg`	`firstleg-service`	9202	头程履约服务，负责揽收、入仓、装载、发运和国内到海外的交接事实。
`order`	`order-service`	9204	订单服务，负责头程订单草稿、提交、状态编排、主数据快照、快递履约信息和订单事件。
`warehouse`	`warehouse-service`	9205	国内仓储服务，负责仓库、地址、收货能力和往来单位配置；往来单位表位于 `baiyue_warehouse.wh_partner`。
`file`	`file-service`	9206	文件中心，负责企业资质和业务文件的上传、下载、元数据、授权与后续对象存储适配。
`print`	`print-service`	9207	打印中心，负责打印模板、打印任务、状态记录及生成文件关联。
`audit-service`	`audit-service`	按配置	审计服务，负责关键操作、租户、操作者、业务对象和追踪号的审计留痕。
`integration-service`	`integration-service`	按配置	外部集成服务，负责承运商、渠道和第三方接口的适配、映射、回调与幂等。
`event-bridge-service`	`event-bridge-service`	按配置	跨区域事件桥，负责版本化事件、Inbox 幂等、投递记录、重试和后续国内外通信。

3. 不单独创建 GitLab 仓库的公共模块

模块	说明
`platform-bom`	统一公共制品版本清单。
`common-core`	统一返回、错误码和核心基础模型。
`common-web`	全局异常、请求追踪和 Web 公共能力。
`common-security`	JWT、安全上下文、租户和审计操作者能力。
`common-openapi`	Swagger/OpenAPI 公共配置。
`common-audit`	审计事件公共模型与切面。
`common-event-contract`	国内与海外共享的版本化事件契约。

这些模块随头程仓发布到 Maven 私有仓库，尾程只能按固定版本引用，不能复制源码或再次发布同一坐标。

4. GitLab 仓库设置建议

保护 main 分支，禁止直接推送和强制推送。
合并必须通过流水线，并至少由一名维护者审核。
开启提交记录、合并请求和发布标签保护。
CI/CD 变量中保存测试或部署环境密码，不提交 .env、本地配置或密钥。
制品保留 7 天；正式发布通过版本标签长期保留。
服务使用独立镜像标签和部署版本，但共同关联同一个 Git 提交号。

5. 第一次推送命令

先在 GitLab 创建空项目，不要勾选 README 初始化。将下面地址中的组织名替换为实际 GitLab 组：

Set-Location D:\baiyue-firstleg
git status
git add .
git commit -m "初始化百悦头程微服务平台"
git branch -M main
git remote add origin https://gitlab.example.com/你的组织/baiyue-firstleg.git
git push -u origin main

如果本地已经存在 origin：

git remote set-url origin https://gitlab.example.com/你的组织/baiyue-firstleg.git
git push -u origin main

推送前必须确认 git status 中没有 target、.idea、日志、上传文件、数据库导出或包含密码的本地配置。

6. 后续确需按服务拆仓时的前置条件

只有满足以下条件后，才建议把 11 个服务拆成独立 Git 仓库：

platform-bom 和全部 common-* 已发布到可用的 Maven 私有仓库。
每个服务拥有独立父 POM 或只依赖已发布父 POM。
服务间 DTO 已替换为版本化 API 或事件契约，不存在源码级依赖。
每个服务都有独立流水线、镜像、配置、数据库迁移和负责人。
已完成跨仓版本兼容和回滚演练。

当前不满足全部前置条件，因此本次只创建 baiyue-firstleg 一个 GitLab 仓库。

5.4 KiB Raw Blame History Unescape Escape