Golang私有仓库搭建与配置教程

搭建Golang私有仓库的核心是配置Go Module代理与校验机制，而非自建GitHub类服务；需协同私有Git服务（如Gitea）、Athens代理工具及GOPRIVATE环境变量，确保模块路径与URL一致、跳过公共代理与校验、凭据可访问。

搭建 Golang 私有仓库，核心不是自建“类 GitHub 服务”，而是配置好 Go Module 的代理与校验机制，让 go get 能安全、稳定地拉取和发布内部模块。主流做法是结合 私有 Git 服务（如 GitLab、Gitea） + Go Proxy 工具（如 Athens） + GOPRIVATE 环境变量，三者协同工作。

一、准备私有 Git 服务（存放代码）

这是模块源码的托管地，需支持 HTTPS 或 SSH 协议，并能生成有效 Git URL（如 https://git.example.com/internal/utils）。

• 推荐轻量方案：用 Gitea（单二进制、易部署）或 GitLab CE（功能全、适合团队）
• 确保仓库设为私有，并为 CI/CD 或开发者配置对应访问权限（Token 或 SSH Key）
• 模块路径需与仓库 URL 对齐 —— 例如模块导入路径为 git.example.com/internal/auth，则仓库地址必须是 https://git.example.com/internal/auth

二、配置 GOPRIVATE 跳过代理与校验

告诉 Go 工具链：哪些域名下的模块属于“私有”，不走公共 proxy（如 proxy.golang.org），也不校验 checksum（因不在 sum.golang.org 注册）。

• 在终端设置：go env -w GOPRIVATE=git.example.com
• 支持通配符，如 GOPRIVATE=*.example.com,git.internal
• 验证是否生效：go env GOPRIVATE，输出应包含你的域名
• ⚠️ 注意：若同时用 GOPROXY（如 Athens），此设置仍必需，否则 go 命令会尝试走代理并失败

三、可选：部署 Athens 作为私有 Go Proxy

适合中大型团队——缓存外部依赖、审计模块来源、加速构建、支持私有模块的只读代理（配合认证）。

• 下载最新 athens 二进制，运行：ATHENS_DISK_STORAGE_ROOT=/data/athens athens --config-file=config.toml
• 在 config.toml 中启用私有仓库支持（如 allowed_organizations = ["git.example.com"]）
• 客户端设置：go env -w GOPROXY=https://proxy.example.com,direct
• Athens 会自动拉取并缓存私有模块（首次 go get 时需提供 Git 凭据，可通过 ~/.netrc 配置）

四、发布与使用私有模块的实操要点

从编码到上线，注意几个关键动作：

• 初始化模块：go mod init git.example.com/internal/logger（路径必须匹配 Git URL）
• 提交代码后打语义化 Tag（如 v1.2.0），Go 会按 Tag 解析版本
• 其他项目引用：import "git.example.com/internal/logger"，然后 go get git.example.com/internal/logger@v1.2.0
• 若遇 unknown revision，检查：Git 仓库是否可访问、Tag 是否已 push、GOPRIVATE 是否覆盖该域名

基本上就这些。不需要重写 Go 工具链，也不必部署完整代码平台 —— 抓住 URL 一致、GOPRIVATE 显式声明、凭据可访问 这三点，私有模块就能像公开模块一样自然工作。