如何搭建GOPROXY服务器实现离线Go依赖包下载安装

前置说明 #

以下操作分联网预缓存和离线部署两个阶段执行，全程不需要对依赖包做手动打包、路径修改操作，所有GitHub来源的直接/间接依赖都会自动完成缓存。 #

一、联网环境预缓存操作（必须在可正常访问公网的机器上执行） #

• 准备和离线环境操作系统、CPU架构一致的联网机器，安装与离线环境版本一致的Go开发环境。
• 上传goproxy可执行文件到该机器，创建专门的缓存存储目录，执行以下命令启动本地代理服务：

  # 示例：服务监听0.0.0.0的8081端口，所有缓存存在当前路径下的goproxy_cache目录
  ./goproxy -listen 0.0.0.0:8081 -cacheDir ./goproxy_cache
  

• 新开一个终端窗口，将当前机器的Go代理指向刚启动的本地服务：

  go env -w GOPROXY=http://127.0.0.1:8081,direct
  

• 将所有需要在离线环境运行/编译的Go项目源码拷贝到该机器，逐个进入项目根目录执行依赖拉取、编译操作：

  # 拉取全量依赖
  go mod download
  # 执行一次完整编译，确保所有间接依赖也被触发拉取
  go build ./...
  

  这一步执行过程中，所有项目用到的Go模块（包括托管在GitHub上的所有直接、间接依赖）都会被本地运行的goproxy服务自动缓存到之前指定的goproxy_cache目录，不需要手动干预。
• 校验缓存结果：打开goproxy_cache目录，能看到按模块路径分层存储的文件，所有github.com/xxx/xxx路径的依赖都能找到对应版本的缓存文件，即完成预缓存工作，可以停掉本地运行的goproxy服务。

二、离线环境部署配置 #

• 将goproxy可执行文件、完整的goproxy_cache目录拷贝到离线环境的目标服务器上，确保目录有可读权限。
• 在离线服务器上启动goproxy服务，注意不要添加-proxy上游代理参数，避免服务尝试访问公网：

  ./goproxy -listen 0.0.0.0:8081 -cacheDir ./goproxy_cache
  

• 给离线环境内所有需要编译Go项目的机器配置Go环境变量，指向离线环境内的goproxy服务：

  # 将<goproxy服务IP>替换为实际部署goproxy的服务器内网IP
  go env -w GOPROXY=http://<goproxy服务IP>:8081,off
  

  末尾的,off参数表示本地缓存不存在对应依赖时直接返回错误，不会尝试直连公网，避免无意义的网络超时。
• 验证配置：进入任意一个预缓存过的Go项目目录，执行go mod download或go build ./...，依赖拉取、编译全程无网络报错即为配置成功，所有GitHub来源的依赖都会直接从本地缓存返回。

三、补充注意事项 #

• 如果后续需要新增依赖，只需要回到联网环境，保持本地goproxy服务启动，拉取新增的依赖包后，将goproxy_cache目录下新增的缓存文件同步到离线环境的对应目录即可，不需要全量重新拷贝缓存。
• 不要手动修改goproxy_cache目录内的文件结构、文件名，否则会导致模块路径匹配失败，无法正常拉取依赖。
• 如果需要缓存私有GitHub仓库的依赖，只需要在联网预缓存阶段给Git配置好对应仓库的访问权限，拉取成功后缓存到本地即可，离线环境使用时不需要配置任何仓库访问凭证。

内容的提问来源于stack exchange，提问作者Vladimir Kosilov