去年年底我司把代码仓库从公共平台迁到了自建的 GitPuk顺带把企业微信统一认证登录也一起打通了。GitPuk 这个轻量级 Git 服务对于团队不大、又想把代码资产握在自己手里的公司来说确实是个性价比很高的选择。很多团队在建代码托管平台的时候纠结的是“要不要上 GitLab”“Gitea 够不够用”最后还会卡在账号体系上——员工记密码、离职删号、权限回收全是麻烦。今天这篇指南不是官网文档的复读而是我把整套流程从部署到企微登录跑通之后整理出来的实操笔记。这套组合解决的核心问题很简单员工用企业微信扫一下或者点个授权就能直接进 GitPuk不需要再单独立一套账号密码同时 GitPuk 里的权限、通知又能反向回到企业微信的会话里。适合谁看中小型技术团队、运维/DevOps、以及正在纠结内部 Git 服务选型的朋友。就算你是第一次接触 GitPuk按下面的步骤走也能在半小时内搭出一个能用的环境。1. GitPuk 到底是什么为什么值得选1.1 一次内部协作的痛点先说说我遇到的实际场景。前年团队三十多人仓库还放在某公共托管平台上成员都是用个人邮箱注册。麻烦事接踵而至有人离职了权限要挨个手工清理员工用个人邮箱收通知漏看合并请求更别提老板每天担心代码外流。后来管理层下了个死命令必须把代码迁到公司自己的服务器上还要和现有的办公账号体系打通。当时列了一堆需求要能自托管、要轻量、要支持企业微信登录、要能发 Webhook 到企微群。GitLab 功能当然全但对几台小服务器来说太吃内存我司的机器上跑个 GitLab 恨不得占 3-4GB 内存还要单独配 PostgreSQL、Redis维护成本直接拉满。后来试了 Gitea轻是轻但企业微信登录要靠自己写插件或者改配置不够省心。最后看到 GitPuk看到“原生支持企业微信 OAuth”那一条就知道这是对的方向。1.2 和 GitLab、Gitea 相比GitPuk 的取舍GitPuk 的定位很清晰它不是一个试图包含世界万物的重型平台而是把“代码托管、权限管理、Webhook、企微登录”这几件企业最常用的事做到顺手。你可以把它想象成 Gitea 的升级版代餐但集成企业微信这件事又比 GitLab 开箱即用得多。对比项GitLabGiteaGitPuk资源占用高4G 内存只是起步低512MB 能跑低512MB 左右部署复杂度组件多配置复杂简单简单企业微信登录需额外配置/插件需动手改代码或依赖插件原生支持后台填参数即可内置通知/Webhook支持但配置偏重支持支持且能直接对接企微机器人适合规模中大型公司个人/小型团队中小团队企微深度用户GitPuk 的轻是有代价的像 CI/CD 内置流水线、项目级 Wiki 这类重功能它做得比较基础。但我们实际用下来日常 Git 操作、Pull Request、Issue、Webhook 这些核心场景完全足够。如果你团队规模不大运维人手少我建议别再纠结要不要上全家桶先让代码管起来、登录统一起来再考虑扩展能力。2. 20 分钟部署一个能用的 GitPuk 实例2.1 环境准备与资源规划部署前先想清楚你要把 GitPuk 放在哪。我推荐用一台配置还行的 Linux 虚拟机最低 2 核 4GB 内存磁盘 50GB 起步。如果是十人以内的小团队这块配置已经能跑得很舒服如果你有几十人磁盘建议直接给到 100GB因为 Git 仓库的增量历史积累速度比你想象得快。操作系统我建议 Ubuntu 22.04 或 Debian 12主要原因是 Docker 支持好。提前装好 Docker 和 docker compose 插件这里不展开命令了用官方源装就行。另外强烈建议把域名想清楚内网可以用git.internal.company.com之类的名字公网访问则需要一个真实域名并配置解析到这台服务器。企业微信回调地址最终要和你访问 GitPuk 的地址一致这一步越早定好后面少踩坑。还有一个容易被忽略的点数据目录要单独挂载。我习惯把/data/gitpuk目录映射到容器里并且给数据库目录单独建 volume这样将来备份或者迁移直接把目录拷走就行。别把容器里的数据裸放在默认层里一旦容器删了代码可全没了。2.2 用 docker compose 拉起服务GitPuk 官方提供了 Docker 镜像安装方式我用的是 docker compose 方式管理好处是依赖关系一目了然。下面是我实际在用的最小化配置services: gitpuk: image: gitpuk/gitpuk:latest restart: always ports: - 8080:8080 environment: - GITPUK_DB_TYPEmysql - GITPUK_DB_HOSTdb - GITPUK_DB_NAMEgitpuk - GITPUK_DB_USERgitpuk - GITPUK_DB_PASSWORDChangeMe123 - GITPUK_DOMAINhttp://git.internal.company.com volumes: - /data/gitpuk:/data - /data/gitpuk/conf:/etc/gitpuk depends_on: - db db: image: mysql:8.0 restart: always environment: - MYSQL_ROOT_PASSWORDRootChangeMe - MYSQL_DATABASEgitpuk - MYSQL_USERgitpuk - MYSQL_PASSWORDChangeMe123 volumes: - gitpuk_mysql:/var/lib/mysql volumes: gitpuk_mysql:把上面内容存成docker-compose.yml然后在同目录执行docker compose up -d等几十秒打开http://服务器IP:8080你应该能看到初始化页面。第一次访问会让你创建管理员账号这个账号必须记好后面企业微信绑定的配置要用管理员权限进去改。第一次启动后立刻检查GITPUK_DOMAIN这个环境变量。它决定了 GitPuk 生成链接和回调地址时用的基础 URL如果写错后面企业微信登录时跳转会非常乱。纯内网环境就把域名设成内网地址公网环境就设成真实域名。2.3 初始化配置要点创建完管理员账号后先进“全局设置 / 常规”里确认三件事。第一外部访问地址要填成你最终访问 GitPuk 的完整 URL不要用localhost也不要带路径。企业微信授权回调时GitPuk 会把这个地址拼上/auth/wecom/callback如果用localhost企微那边根本无法访问你的服务器。第二如果服务器有公网 IP 和域名强烈建议在前端套一层 Nginx 或 Caddy用 HTTPS 访问。企业微信 OAuth 要求回调地址必须为 HTTPS 或者已校验的域名某些情况下 HTTP 也能填但浏览器跳转时经常会被安全策略拦下来。我的做法是在 Nginx 里配置证书再把 8080 端口反代到 HTTPS 443GitPuk 本身不直接暴露公网。第三估计团队规模并决定是否打开“用户自助注册”。接入企业微信后我希望所有成员都通过企微登录进入这样就不需要再开放密码注册避免出现和员工身份无关的游离账号。在初始化阶段把这个开关关掉后面省很多权限梳理的时间。3. 企业微信集成统一认证登录的接入全流程3.1 统一认证的底层逻辑为什么说企业微信集成能实现“统一认证登录”本质上是一次 OAuth2.0 授权流程。员工在 GitPuk 登录页点击“企业微信登录”GitPuk 会把他引导到企业微信的授权页面员工在企微中确认身份后企微服务器带着一个临时授权 code 跳回 GitPukGitPuk 再用这个 code 调用企微的接口换取用户身份信息最后在本地自动完成账号注册或绑定。用生活里的场景来类比你去园区访客中心前台先问你要一张访客码你再拿访客码去闸机换一张通行证闸机看脸认人。企业微信就是那个发访客码的前台GitPuk 就是闸机。你根本不需要单独再办一张门禁卡。这套方式比本地密码体系强在几个地方员工离职后在企微后台移除身份GitPuk 这边就进不去了员工不需要记住 Git 平台密码安全策略统一由企微管控比如员工离职禁用账号、组织架构调整同步成员范围都能集中管理。3.2 企业微信管理后台里的应用配置要让 GitPuk 能调用企业微信的接口你得先在企业微信管理后台创建一个“自建应用”。打开企业管理后台 - 应用管理 - 应用 - 自建点击创建应用。应用名称随便填比如“Git代码平台”可见范围选全员或者研发部门建议先选一个小范围测试等配置稳定后再扩大到全员。创建成功的应用页面里记住三个关键值CorpID、AgentId、Secret。CorpID 是企业 ID相当于你企业的通用身份标识AgentId 是当前应用的编号Secret 是这个应用的密钥。这三个值后面要原样填进 GitPuk 的配置里千万注意 Secret 复制时不要把首尾空格带进去否则校验死活不过。接下来是重头戏配置 OAuth2.0 回调地址。在企业微信后台该应用的“开发者接口”里找到网页授权及 JS-SDK 配置把域名加进可信域名。如果你用 GitPuk 容器自带的服务要填入的可信域名就是git.internal.company.com并在配置里上传校验文件到/data/gitpuk/conf对应目录让企微能验证这个域名确实是你控制的。然后还要在网页授权里配置https://git.internal.company.com/auth/wecom/callback作为授权回调地址。不要忘了配置企业可信 IP。企业微信的 API 有 IP 白名单限制只有白名单内的服务器出口 IP 才能调用getuserinfo这类接口。把 GitPuk 所在服务器访问公网时的出口 IP 加到应用的“企业可信IP”列表里不然登录时会出现“回调校验失败”或“获取用户信息错误”。3.3 GitPuk 侧开启企业微信登录回到 GitPuk 管理界面进入“认证源”或“登录设置”菜单。不同版本菜单名称略有差异一般都能在“管理后台 - 认证与安全 - OAuth 应用”里找到。新建一个认证源类型选择“企业微信”。把刚才抄下来的 CorpID、AgentId、Secret 填进对应字段。回调地址一栏通常会自动生成常见格式是https://git.internal.company.com/auth/wecom/callback这个地址必须和企业微信后台填写的回调地址完全一致一个字符都不能差。保存后回到登录页刷新一下应该能看到“企业微信登录”的按钮。首次登录时GitPuk 会在本地自动创建账号。主键是最能唯一定位到员工身份的userid也就是员工在企业微信里的英文 ID。创建出来的账号默认是普通成员权限不会自动给管理员权限。如果想给某个员工管理员权限需要域管理员在用户管理里把他加入管理员组。3.4 登录后的权限与团队映射统一认证只是第一步真正省心的是把组织和代码仓库权限联动起来。GitPuk 支持通过企业微信的通讯录同步部门信息也就是说你在企微后台划分了“研发部”“测试部”“设计部”GitPuk 也能按同样的部门结构创建团队或成员组。我建议的配置策略是在 GitPuk 里按团队建组织/组比如backend、frontend、qa然后在“管理后台 - 同步配置”里开启“部门同步”。这样研发同事入职后企微通讯录里被加进对应部门GitPuk 当天或按设定周期自动同步到对应组离职时移除通讯录成员同步后权限自动失效。省掉了原来手工维护权限表的痛苦。需要注意同步部门不等于同步仓库授权。仓库级别的读写权限最好还是用组的角色来控制。我司的做法是每个代码仓库归属到某个组组内成员默认有读权限维护者写权限再通过企微组名映射自动添加成员。这样不管员工调岗还是离职权限基本都能自动收敛。4. 接入企微之后的日常使用与自动化4.1 仓库、分支保护与 Code ReviewGitPuk 接入统一认证后代码协作体验会顺很多。仓库管理上我习惯把main或master设为受保护分支禁止直接推送所有变更必须走 Pull Request并且至少指定一名 Reviewer。实际操作中在 GitPuk 的仓库设置里找到“受保护分支”添加规则允许维护者合并允许开发者创建分支但不允许直接 push 到主分支。这样做的好处是代码评审从“可选项”变成了“必经流程”而每个评审通知都会带上评审人在企微里的身份。员工点开会直接跳到对应的 Pull Request 页面不再需要反复输入密码或者切换账号。对于还没有 Code Review 文化的团队这套流程能倒逼大家养成习惯。4.2 用 Webhook 把 GitPuk 事件推到企微群GitPuk 内置了 Webhook 能力可以订阅各种事件。最实用的场景是把代码推送、合并请求创建、评审评论、Issue 更新等事件实时推送到企业微信的某个群机器人。具体操作在企业微信群里添加一个“群机器人”复制它的 Webhook 地址。然后在 GitPuk 仓库的“管理 - Webhook”里新建一条 Webhook把机器人地址填进去事件类型按需勾选。GitPuk 默认的 payload 格式需要整理一下才能更好看我自己写了一个很简单的 Python 脚本作为中间层把 GitPuk 的 JSON 转成企微机器人认识的 Markdown 消息再 POST 到企微 Webhook。发送消息的格式类似这样curl https://qyapi.weixin.qq.com/cgi-bin/webhook/send?keyREPLACE_KEY \ -H Content-Type: application/json \ -d { msgtype: markdown, markdown: { content: 仓库 [backend] 有新合并请求font color\info\#123 优化登录模块/font\n提交人张工\nhttps://git.internal.company.com/backend/backend/pulls/123 } }注意企微群机器人对消息频率有限制同一机器人每分钟最多 20 条。如果团队活跃度高可以在中间层做聚合把多条事件合并成一条摘要再发送否则群消息刷屏大家会直接屏蔽掉。4.3 员工如何用企微身份完成协同闭环接入统一认证后感受最直观的是“一条龙闭环”。举个我司常见的例子小周在企微里收到群机器人提醒“前端代码库有新合并请求待评审”点一下链接浏览器自动打开 GitPuk因为已经具备企微登录态页面直接定位到 PR 的 diff 视图。他在评论里回了句“这个错误提示文案需要改”GitPuk 会给提交人发通知提交人查看后重新推送代码合并请求自动触发 Webhook 再发回群里。整个过程里大家不需要关心账号是什么也不需要反复登录多个系统。员工在企微里的姓名、头像直接显示在 GitPuk 的提交评论和文件修订历史里追溯代码变更时一眼就能看出是谁干的。对于管理者这套体系还提供了审计价值谁在什么时间点审批了哪次合并全部有记录。5. 常见问题与排查手记5.1 登录失败十有八九是回调地址和可信域名我调试企微登录时遇到的坑九成以上出在回调配置上。现象是点击“企业微信登录”后页面提示“redirect_uri 参数错误”或者“应用无法访问”。第一件事不是看代码而是核对三处企业微信后台填写的回调地址、GitPuk 认证源配置里的回调地址、浏览器地址栏里的回调地址到底长什么样。还有一次怎么都拿不到用户信息后来发现服务器出口 IP 变了企业微信可信 IP 列表里还是旧 IP。如果是网络拨号环境出口 IP 会变要在企微管理后台及时更新或者在防火墙上固定出口 IP。排查速查表现象可能原因处理方式跳转后提示 redirect_uri 错误回调地址不一致逐字对比两个配置提示回调域名未校验可信域名校验文件没放对位置把拿到的校验文件放到 GitPuk 站点根目录并保证可访问授权后报“获取用户信息失败”Secret 错误或可信 IP 未配置重新复制 Secret添加入口 IP登录成功后没有自动分配角色未开启部门同步在认证源设置里开启同步并检查企业微信可见范围按钮不显示认证源未启用在 GitPuk 管理后台把认证源状态改为启用5.2 麒麟系统怎么用企业微信客户端很多信创办公机器用的是麒麟操作系统群里经常有人问“企业微信是不是没有 Linux 版本”或者“麒麟安装包哪里找”。实际体验下来企业微信本身是提供 Linux 版安装包的麒麟系统可以下载对应架构的 deb 包安装。装好之后企业微信的聊天、群机器人、扫码授权功能都可以正常工作足以应付 GitPuk 的扫码登录场景。如果实在装不上原生客户端也可以直接用企业微信的网页版。GitPuk 的“企业微信登录”本质是 OAuth 授权网页版里同样能完成扫码和同意授权操作。团队成员用什么客户端不影响 GitPuk 登录流程。唯一要提醒的是Linux 客户端版本更新可能滞后遇到登录态失效时先检查客户端是否需要更新。5.3 多开会封号统一认证不背这个锅关于“企业微信多开会封号吗”的热搜我多说一句。企业微信登录风险管理主要针对异常设备和异常登录行为比如模拟器、批量注册、频繁切换 IP、使用非官方多开工具。像 GitPuk 这类通过官方 OAuth 授权登录使用的是标准接口员工在可信设备上正常登录完全不会触发风控。如果团队同学中确实有人用非官方工具在同一台电脑上开多个企微账号那是账号安全层面的风险和 GitPuk 统一认证没有关系。作为管理员我的建议是明确规则统一认证走的是安全通道不鼓励用任何破解多开工具。正经业务不需要靠歪门邪道来“防封”稳定登录才是正解。5.4 存储空间满了怎么清理GitPuk 跑了一段时间后会出现磁盘告警。主要还是仓库的.git目录增长快加上 MySQL 数据库的 binlog 和容器日志。我通常三个方向处理。第一个是 Git 仓库瘦身。在 GitPuk 的仓库维护页面执行 GC垃圾回收和 LFS 清理本地对应仓库也可以在服务器上执行git gc --aggressive --prunenow第二个是清理 Docker 日志。GitPuk 容器默认会一直写日志时间一长文件很大。可以在docker-compose.yml里限制日志大小logging: driver: json-file options: max-size: 10m max-file: 3第三个是 MySQL 本身。定期清理不再需要的仓库附件、临时文件和旧构建产物并检查数据库表的膨胀情况。如果你有云存储空间也可以把归档仓库冷备份后从平台移除。总之磁盘规划从一开始就要留够别等满了再动手。5.5 有没有更进一步的扩展侧边栏和智能助手接入之后可以玩的花样还有不少。比如把 GitPuk 链接嵌进企业微信侧边栏成员在工作台里一键跳到代码平台用企微机器人在群里输入/repo就能返回仓库状态甚至可以把 GitPuk 的 Webhook 接到企业微信智能助手实现“在群里直接创建 Issue、查看合并请求状态”。侧边栏的实现本质就是企业微信自定义页面把 GitPuk 的登录地址嵌进去因为已经统一认证了打开就是免登状态。这里的坑是侧边栏对页面宽度有限制GitPuk 界面要稍微做点响应式适配否则菜单会被挤掉。智能助手则需要写一点回调消息的逻辑适合对开发有瘾的团队自己去折腾。6. 踩过一圈坑之后的实践体会如果只能给大家留一句话先把域名和回调地址的规矩定死再碰镜像部署。我前面很多问题都是因为域名改来改去导致企微后台回调地址、GitPuk 配置和 Nginx 反代三者对不上排查起来相当费神。第二点体会是不必急着追求“所有功能一步到位”。我最初把 GitPuk、企微登录、Webhook、群机器人、部门同步全安排上结果上线第一天手忙脚乱。后来拆成两个阶段先把登录和仓库权限跑通稳定运行一周后再加通知和自动化。这样每次变更的影响面小也方便排查。最后再分享一个小技巧把 GitPuk 的备份脚本写进 cron每天凌晨打包/data/gitpuk和 MySQL volume备份到另一台机器或对象存储。代码平台无小事备份永远不嫌多。这套组合我这边运行了几个月企业微信登录成功率稳定在 99% 以上团队也没有再为账号的事找过运维。希望这轮实操笔记能让你少走几步弯路。