Go 三服务在线优先、离线回退编译与发布流程

本文记录一套面向定制 Linux 环境的 Go 构建方案：仓库内固定 Go 工具链，有网时优先从模块代理解析依赖，无网或在线编译失败时自动切换到仓库内的共享 vendor，最终生成三个可直接部署的 Linux x86_64 静态可执行文件。

一、背景与目标

定制系统上的软件版本、动态库和运行环境通常经过整体验证。为了编译一个 Go 项目去更换 yum/apt 软件源，或者升级系统已有组件，风险往往大于收益。另一方面，构建服务器的网络条件也不一定稳定，完全依赖公网会让发布流程失去可预期性。

这套方案遵循以下原则：

1. 不安装或升级系统软件，不修改系统软件源。
2. Go 版本和工具链校验值由仓库固定。
3. 有网时使用模块代理，但不自动修改 go.mod 和 go.sum。
4. 无网或在线编译失败时，整体回退到共享 vendor。
5. 只构建指定的三个服务，不扫描和发布其他模块。
6. 在临时目录完成全部编译，成功后再替换正式产物。

二、整体流程

这里的“在线”仅指 Go 模块依赖解析。脚本不会执行 git pull、go get 或 go mod tidy，也不会动态更新业务代码。

三、构建目录设计

项目的 Go 构建入口位于：

src_go/build/
├── build.sh
├── README.md
├── go.work
├── go.work.sum
├── go_list.txt
├── toolchain.env
├── runtime/
│   ├── gocontrol.sh
│   ├── cygfileweb.sh
│   ├── cygauditweb.sh
│   └── cygimagealgoweb.sh
├── toolchains/
│   └── go1.25.12.linux-amd64.tar.gz
└── vendor/
    ├── modules.txt
    └── ...

首次执行后会在本地生成缓存：

src_go/build/.cache/
├── toolchains/
│   └── go-1.25.12/
├── go-build/
├── gopath/
└── work/

.cache/ 只是当前工作区的解压和编译缓存，不应提交到版本管理。删除它不会丢失源码，下次构建只会重新解压工具链并生成缓存。

四、固定 Go 工具链

toolchain.env 锁定构建工具版本、归档文件名和 SHA256：

GO_VERSION="1.25.12"
GO_ARCHIVE="go1.25.12.linux-amd64.tar.gz"
GO_ARCHIVE_SHA256="234828b7a89e0e303d2556310ee549fbcf253d28de937bac3da13d6294262ac1"

构建前可以先做轻量检查：

cd src_go/build
./build.sh --check

检查项包括：

• 当前主机必须是 Linux x86_64。
• 内置 Go 归档必须存在，SHA256 必须一致。
• 共享 vendor/modules.txt 必须存在。
• 三个目标模块都必须包含 go.mod 和 main.go。
• 四个运行脚本必须完整。

通过校验后，工具链被解压到项目缓存目录，而不是 /usr/local/go 或其他系统目录。脚本还会设置：

GOTOOLCHAIN=local
GOENV=off
CGO_ENABLED=0
GOOS=linux
GOARCH=amd64

GOTOOLCHAIN=local 防止 Go 根据模块声明自动下载另一套工具链，GOENV=off 避免用户全局 Go 配置干扰本次构建。

五、管理三个目标服务

go_list.txt 是唯一的目标清单：

sunri-cygfileweb
sunri-cygauditweb
sunri-cygimagealgoweb

脚本会将模块名前缀 sunri- 去掉，生成下列产物：

源码模块	可执行文件
sunri-cygfileweb	cygfileweb
sunri-cygauditweb	cygauditweb
sunri-cygimagealgoweb	cygimagealgoweb

当前脚本要求清单中必须且只能包含三个目标。这是有意的发布边界：新增服务时不能只改文本清单，还需同步增加运行脚本、检查规则和发布验证。

go.work 统一引用三个服务和内部组件模块，使构建可以直接使用当前仓库中的源码，不需要把内部模块先发布到远程代理。

六、在线优先的依赖策略

6.1 默认在线编译

直接执行：

cd src_go/build
./build.sh

脚本默认使用：

GOPROXY=https://goproxy.cn,direct
GOSUMDB=sum.golang.google.cn

它先提取 GOPROXY 中的第一个 HTTP/HTTPS 地址，通过 curl 或 wget 做最长 8 秒的访问探测。代理可访问时，三个服务使用以下模式编译：

go build -mod=readonly ...

-mod=readonly 允许 Go 从模块代理下载缺少的依赖，但当构建需要修改 go.mod 时会直接失败。这样可以使用在线缓存，同时避免发布脚本暗中改变依赖声明。

如果内网有自己的 Go 模块代理，可显式覆盖：

GOPROXY='http://go-proxy.example.internal,direct' \
GOSUMDB='off' \
./build.sh

只有经过组织安全策略允许时才应设置 GOSUMDB=off。能使用可访问的校验服务时，应保留模块内容校验。

6.2 自动回退到共享 vendor

出现以下任一情况时，脚本会切换到离线模式：

• GOPROXY 的首个地址不是 HTTP/HTTPS 地址。
• 系统同时缺少 curl 和 wget。
• 模块代理连接超时或返回错误。
• 在线模式下的任意服务编译失败。

回退时会重置依赖相关环境：

GOPROXY=off
GOSUMDB=off
go build -mod=vendor ...

在线和离线编译使用两个独立的临时目录。如果第二个服务才在线编译失败，脚本不会把第一个服务的在线产物与后续离线产物混合，而是使用 vendor 重新构建三个服务。

6.3 强制离线编译

已知构建机处于断网环境时，可以跳过网络探测：

GO_BUILD_OFFLINE=1 ./build.sh

这个变量只允许设置为 0 或 1，其他值会立即报错。

七、编译参数与产物特性

三个服务使用相同的编译参数：

go build \
  -buildvcs=false \
  -mod='<readonly 或 vendor>' \
  -trimpath \
  -ldflags='-s -w -buildid=' \
  -o '<临时输出路径>' \
  .

参数	作用
-buildvcs=false	不在产物中嵌入 Git 提交元数据
-mod=readonly	在线解析依赖，禁止修改模块声明
-mod=vendor	只使用共享 vendor
-trimpath	去除编译机本地绝对路径
-s -w	移除符号表和 DWARF 调试信息，减小产物体积
-buildid=	不写入默认 Go build ID

配合 CGO_ENABLED=0 可生成不依赖目标机 C 运行库的静态可执行文件。这样的产物更适合部署到软件环境特殊的定制 Linux 系统。

需要注意：在线构建与 vendor 构建的业务代码可以相同，但 Go 仍可能把不同的模块信息写入二进制元数据，因此两种模式的 SHA256 不一定相同。验收时应关注工具链、依赖版本、架构和功能是否一致，不应默认两种依赖模式必然产生相同哈希。

八、产物发布

编译成功后，脚本将可执行文件和运行脚本发布到：

binary/java/
├── bin/
│   ├── gocontrol.sh
│   ├── cygfileweb.sh
│   ├── cygauditweb.sh
│   └── cygimagealgoweb.sh
└── jar/x64/
    ├── cygfileweb
    ├── cygauditweb
    └── cygimagealgoweb

Go 产物放在 binary/java/jar/x64/ 是为了兼容项目已有的发布目录和启停管理约定，不表示这些文件是 Java Jar。

每个产物都先以临时文件名写入正式目录，再使用 mv 替换目标文件。这可以避免拷贝中途被打断时，正式路径留下半个可执行文件。

如果同一轮版本同时构建 Java 和 Go，应按以下顺序执行：

1. 先执行 Java 打包
2. 再执行 Go 打包

原因是 Java 打包流程可能重建 binary/java/jar/x64/ 目录。如果先放入 Go 产物，后续 Java 构建可能将它们删除。

九、自定义构建参数

环境变量	默认值	用途
GO_BUILD_OFFLINE	0	设为 1 时强制使用共享 vendor
GOPROXY	https://goproxy.cn,direct	在线模块代理及回源策略
GOSUMDB	sum.golang.google.cn	Go 模块校验服务
GO_BUILD_CACHE_DIR	src_go/build/.cache	解压工具链和构建缓存目录
GO_BINARY_ROOT	V1.00/binary	覆盖发布输出根目录

例如，需要在不影响正式产物的前提下试编译：

GO_BUILD_CACHE_DIR=/tmp/prs-go-cache \
GO_BINARY_ROOT=/tmp/prs-go-output \
./build.sh

成功后的试编译产物位于：

/tmp/prs-go-output/java/jar/x64/

十、部署与启停

上传完整项目后，先配置 PRJHOME：

export PRJHOME=/home/sunri/PRS7012-AMP/01_开发库/V1.00

然后使用各服务脚本管理进程：

cd "$PRJHOME/binary/java/bin"

./cygfileweb.sh start
./cygfileweb.sh status
./cygfileweb.sh restart
./cygfileweb.sh stop

./cygauditweb.sh start
./cygimagealgoweb.sh start

服务脚本会根据 PRJHOME 定位默认产物。底层 gocontrol.sh 还可以在已有平台环境中根据 CYGHOME、PLATVERSION 和 APPVERSION 尝试兼容路径。

启动前建议先检查文件权限和架构：

ls -l "$PRJHOME/binary/java/jar/x64/"
file "$PRJHOME/binary/java/jar/x64/cygfileweb"

期望结果应包含：

ELF 64-bit LSB executable, x86-64, statically linked, stripped

十一、日常验收清单

每次修改 Go 代码、依赖或构建脚本后，建议至少执行：

cd src_go/build

./build.sh --check
./build.sh

file ../../binary/java/jar/x64/cygfileweb
file ../../binary/java/jar/x64/cygauditweb
file ../../binary/java/jar/x64/cygimagealgoweb

sha256sum ../../binary/java/jar/x64/cygfileweb \
  ../../binary/java/jar/x64/cygauditweb \
  ../../binary/java/jar/x64/cygimagealgoweb

如果本次调整涉及离线依赖，还应单独验证：

GO_BUILD_OFFLINE=1 ./build.sh

不要只检查命令退出码。产物必须同时满足：

• 三个文件都存在且具有可执行权限。
• file 识别为 Linux x86_64 ELF。
• 产物是 statically linked。
• 正式输出目录中没有遗留 .*.tmp.* 文件。
• go.mod、go.sum 和 go.work.sum 没有被构建过程意外修改。

十二、常见问题

12.1 Go 工具链 SHA256 不匹配

日志示例：

[go-build] 错误: SHA256 不匹配: ...go1.25.12.linux-amd64.tar.gz

说明内置归档不完整，或已经被替换。应从可信来源重新准备对应版本的归档，重新计算并复核 SHA256。不要为了让检查通过而直接把锁定值改成当前文件的哈希。

12.2 代理不可达后仍然编译

日志可能显示：

[go-build] 网络不可用，自动使用共享 vendor

这是预期的降级路径，不是故障。只要后续三个服务全部编译成功，产物就可以发布。

12.3 共享 vendor 编译失败

如果在线构建能通过，但强制离线失败，通常说明：

• vendor 缺少新增依赖。
• vendor/modules.txt 与各模块的 go.mod 不一致。
• go.work 没有包含新增的本地模块。
• 业务代码依赖了一个未纳入工作区和 vendor 的内部包。

应在有网、工具链受控的环境中重新整理工作区依赖，再生成共享 vendor，审查变化后连同 modules.txt 一起提交。不要在断网发布机上临时拼接依赖。

12.4 提示找不到可执行文件

日志示例：

错误: 未找到 Go 可执行文件: cygfileweb

优先检查：

echo "$PRJHOME"
uname -m
ls -l "$PRJHOME/binary/java/jar/x64/cygfileweb"

当前构建脚本只生成 x86_64 产物。如果目标机是 ARM64，运行脚本会尝试寻找 jar/arm64/，但本流程不会为它生成产物。

12.5 强制离线参数不合法

日志示例：

[go-build] 错误: GO_BUILD_OFFLINE 只能设置为 0 或 1

不要使用 true、yes 等值，正确写法是：

GO_BUILD_OFFLINE=1 ./build.sh

12.6 Java 构建后 Go 产物消失

这不是 Go 编译失败，而是两套发布流程共用了目标目录。将同一轮版本的执行顺序固定为“先 Java，后 Go”即可。

十三、依赖变更规范

当业务代码引入新的第三方模块时，不能只以“在线构建成功”作为验收结论。完整流程应包括：

1. 在有网环境中确认模块版本。
2. 审查 go.mod、go.sum 和 go.work.sum 变化。
3. 重新生成并审查共享 vendor。
4. 执行默认在线构建。
5. 执行 GO_BUILD_OFFLINE=1 ./build.sh。
6. 确认两种模式都生成三个服务。
7. 将模块声明、校验文件和 vendor 变化放在同一次提交中。

这样才能保证当前有网可构建，未来断网也可构建。

十四、总结

这套 Go 构建流程的核心不是“永远在线”或“永远离线”，而是把开发效率和交付可靠性同时保留下来：

• 有网时优先利用模块代理和本地缓存。
• 网络不可用时不中断发布，而是回退到受版本管理的 vendor。
• 构建机无需安装 Go，也不需修改系统环境。
• 三个服务使用同一工具链、工作区和发布边界。
• 在线和离线产物不混用，发布过程只接收一套完整结果。

对于网络条件不稳定、又必须尽量保持系统原状的构建服务器，这种“固定工具链 + 在线优先 + vendor 回退 + 临时目录发布”的组合，能显著降低环境差异和网络波动带来的构建风险。