你有没有遇到过这种情况：团队内部已经全员使用企业微信，却还要每个人单独注册一套代码托管平台的账号。管理员每天审批新成员、找回密码、处理重名账户，累得够呛。GitPuk是一款面向中小团队的轻量级Git托管服务，部署成本低，更关键的是它原生支持企业微信集成，可以把企业微信直接变成登录入口，扫码或者点一下授权就完成身份认证。这篇指南面向正在准备部署GitPuk、或者已经部署但不想再维护一套账号体系的同学，从企业微信侧的参数准备开始，一路讲到GitPuk的配置、启动、排错，尽量把关键节点都说清楚。
1. 为什么GitPuk要把企业微信做成统一登录入口
在讲具体操作之前，先把为什么这么做说清楚。很多人以为“集成企业微信登录”只是省一个密码，其实它解决了代码托管平台在企业落地时最头疼的几个问题。你把它看成一个身份入口的改造，而不是单纯加一个按钮。
我在帮几家公司搭GitPuk的时候，几乎所有人第一个要求都是“能不能用企业微信登录”。原因很简单：公司已经通过企业微信管理考勤、审批和内部沟通，员工每天都要打开它，直接用企业微信扫码是不需要额外学习成本的。而GitPuk自带的本地账户体系在规模稍大一点后就成了管理黑洞，光是维护用户列表就够受的。
1.1 GitPuk适合什么样的团队
GitPuk在架构上很像Gitea，主打轻量、单二进制、低资源占用，但它更贴心的是把企业微信、飞书、钉钉这类国产IM的OAuth适配做成了默认能力。对于50人以下、没有专职运维的研发团队来说，这个定位很合适。你不需要配一台8核16G的机器去跑GitLab，一台1核2G的小实例就能把代码托管跑得很稳。
如果你所在团队已经全员用企业微信，那GitPuk几乎就是开箱即用的。它自带Web界面、分支合并请求、Issue跟踪、Webhook通知，日常研发工具链该有的都有了。你可以把它部署在内部服务器上，也可以放到云主机上，数据落在自己手里，不会因为SaaS服务不稳定而影响代码访问。相比GitLab，它更轻；相比Gitea，它省掉了自己写OAuth插件的工作量。
1.2 统一认证登录解决的痛点
统一认证带来的最直接价值是账号生命周期管理。员工入职时，企业微信账号已经开通，扫码就能登录GitPuk，不用管理员手动创建账号、分配初始密码。员工离职后，管理员把企业微信通讯录里的成员停用，GitPuk这边由于认证源失效，该员工基本就无法再登录了。就算之前本地账号还没删，认证环节已经帮他挡住了访问，这比事后翻审计日志找离职员工登录记录要靠谱得多。
另外，统一认证减少了“密码疲劳”。团队成员不用再为GitPuk单独记一套密码，自然也就不存在“用公司邮箱注册GitPuk，密码忘了，发邮件找回”这种走流程的低效操作。如果你同时部署了Wiki、任务管理、自动化部署等多套内部系统，统一认证的价值会被进一步放大：员工只需要在企业微信里授权，就能在不同系统间自由切换，而管理员只需要维护一套账号数据。
1.3 为什么是企业微信而不是LDAP/SAML
很多传统团队习惯用LDAP做统一认证，但LDAP通常依赖公司内网目录服务，搭建和维护成本都不低，而且对外网用户不友好。SAML协议功能强大，但配置复杂，一般需要专门的认证服务器，适合大型企业，放到一个轻量Git服务上有点大材小用。企业微信的OAuth2授权登录则像一把轻便钥匙：它不需要你维护目录服务，用户身份由企业微信云端保管，你只需要在GitPuk配置几个参数。
企业微信更大的优势在于通讯录开放API。统一认证只是身份的“入口”，而通讯录同步可以带出部门、职位、直属上级等组织关系。也就是说，GitPuk不仅能验证“你是谁”，还有机会掌握“你在哪个部门”，这为后续的按团队授权、自动化建组提供了数据基础。综合考虑维护成本、上手难度和国内团队的实际情况，企业微信是当前最稳妥的选择。
2. 准备工作：企业微信侧的应用创建与配置
这部分是很多人容易卡住的地方。GitPuk配置本身不难，难在企业微信后台的几十个选项里找不到正确入口。我按自己的操作顺序来写，你最好一步一步跟着走，避免漏掉某个校验。
开始前先确认一件事：你的企业微信必须是认证企业。没有完成企业认证的话，很多自建应用和接口权限都开不了。这一步没法绕过，先跟公司行政或企业主账号管理员确认好。
2.1 获取三位关键参数
登录企业微信管理后台，在“我的企业”最底部能看到企业ID，文档里通常写作CorpID。这个参数标识你所属的企业，GitPuk需要知道它要跟哪个企业微信租户完成OAuth握手。接着进入“应用管理”页面，点击“应用”下的“自建”，创建一个自建应用，类型选择“普通应用”。创建完成后，详情页会展示AgentId和Secret两个参数，AgentId是应用编号，Secret是应用密钥。
注意Secret只在创建时完整展示一次，之后只能重置，不会给你完整明文。我习惯把它复制到本机密码管理器里，再配合环境变量使用。这三个参数就是GitPuk和企业微信之间通信的钥匙：CorpID指明企业身份，AgentId指明具体应用，Secret则是调用企业微信接口时的凭证，缺一不可。
2.2 配置可信域名与回调地址
在自建应用详情页找到“网页内容及JS-SDK”配置区域，需要先配置“可信域名”。可信域名本质上是一个所有权校验：企业微信会要求你在该域名的根目录下放置一个指定文件，用来证明域名是你可控的。这里有个很隐蔽的坑，可信域名不要带http://或https://，直接填写域名，比如git.example.com，但路径校验文件要能通过公网访问。
接下来设置“网页授权域名”和“回调域名”。网页授权域名是企业微信执行OAuth跳转时允许使用的域名，一般也为git.example.com。回调域名理论上不用单独再设置，但如果你启用了消息接收，就必须再填一次。GitPuk配置的后端地址是/auth/wecom/callback，所以完整的回调地址是https://git.example.com/auth/wecom/callback。后端这个路径必须固定，不要为了好看改成其他路径。
2.3 服务器与域名要求（含备案）
GitPuk本身对服务器要求很低，但要让企业微信能顺利回调，你的GitPuk必须有一个公网可以访问的域名，并且全程HTTPS。企业微信的OAuth强制要求回调地址使用HTTPS协议，所以不能用裸IP访问，也不能直接写http://内网IP。域名如果托管在国内服务器上，通常需要完成ICP备案，否则接入过程中会被卡住，这属于国内网络环境的正常合规要求，提前办比较省事。
我推荐的最小部署方案是用一台1核2G的云主机，安装Nginx做反向代理，上面挂一个Let's Encrypt免费SSL证书，然后把git.example.com转发到GitPuk的3000端口。这样企业微信回调时看到的是标准HTTPS地址，本地服务只要在本机监听HTTP端口即可，不需要在GitPuk内部自签证书。
2.4 创建应用时常见的坑
第一个坑是可信域名填写错误，我见过有人把域名填成了http://git.example.com/path，结果校验文件一直找不到。记住这里只要域名，不带协议、不带路径。第二个坑是回调地址不一致：企业微信后台记录的回调域名是git.example.com，但GitPuk外部URL配置成了localhost:3000，跳转后企业微信会报redirect_uri参数错误。第三个坑是应用权限没有配置出口IP白名单，如果你在应用详情里设置了“企业可信IP”，那么GitPuk服务器所在公网IP必须加进去，否则获取token的接口会返回60020错误码。
另外，自建应用一旦创建后，不要随意修改AgentId或Secret，哪怕只改其中一个，GitPuk也会立即丢失身份验证能力。如果你改动了，记得同步更新GitPuk的环境变量，并重启服务。
3. GitPuk部署与OAuth配置实操
企业微信那边准备好后，就可以开始部署GitPuk了。这一节我按最省心的Docker Compose方式写，其他方式比如裸二进制安装后面补充一下。如果你已经跑起来了，也可以跳到3.3节只更新OAuth参数。
3.1 用Docker Compose快速部署
我强烈建议第一次部署直接用Docker Compose，省去编译、依赖、systemd脚本这些问题。你只需要准备一个docker-compose.yml，内容大致如下：
services: gitpuk: image: gitpuk/gitpuk:1.4.2 container_name: gitpuk ports: - "127.0.0.1:3000:3000" volumes: - ./gitpuk-data:/data environment: - GITPUK_EXTERNAL_URL=https://git.example.com - GITPUK_HTTP_PORT=3000 - GITPUK_DATABASE=/data/gitpuk.db - WECOM_CORP_ID=wwxxxxxxxx - WECOM_AGENT_ID=1000002 - WECOM_SECRET=your-secret restart: unless-stopped注意我把端口绑到了127.0.0.1:3000，因为前面建议用Nginx做反代，所以没必要直接暴露端口到公网。GITPUK_DATABASE指向/data目录下的SQLite文件，整个数据目录通过volume挂到了宿主机上，后续升级容器不会丢数据。如果你的团队规模在100人以下，SQLite完全够用，不用额外再上PostgreSQL。
3.2 配置文件与环境变量详解
GitPuk支持环境变量和配置文件两种方式，我推荐环境变量，因为可以通过.env文件统一管理，也方便后续迁移到K8s或云平台的Secret管理。关键配置就几项：GITPUK_EXTERNAL_URL控制所有外部跳转链接，尤其影响回调地址；GITPUK_HTTP_PORT是容器内部监听端口；GITPUK_DATABASE是数据库文件路径；WECOM_*系列是企业微信参数。
这里尤其注意Secret的安全：不要直接写死在镜像或提交到Git仓库。我一般把真实的.env放在服务器上，用chmod 600限制权限，然后把.env.example模板放进代码库，只留字段名不留值。这样即使有人看到代码仓库，也不会泄露生产密钥。另外，WECOM_SECRET和WECOM_CORP_ID一定不能填反，否则认证阶段会返回corpid与secret不匹配。
3.3 写入企业微信参数并启动
先把企业微信后台拿到的CorpID、AgentId、Secret填入上面环境变量，然后执行docker compose up -d。第一次启动时建议用docker compose logs -f观察输出，正常情况下会看到类似“Web server listening on 0.0.0.0:3000”的日志。如果你已经设置了WECOM_SECRET，启动日志里不会显示明文，只会在debug模式下打印WeCom OAuth provider initialized一类的提示。
启动完成后，用浏览器访问http://127.0.0.1:3000，登录页应该能看到“企业微信登录”按钮。这一步如果没出现，先检查环境变量是否加载成功，比如用docker compose exec gitpuk env | grep WECOM查看容器里的变量值。如果变量为空，多半是.env文件没有放在docker-compose.yml同级目录下，Compose默认不会读取其他路径。
3.4 验证登录流程是否跑通
点击登录页上的企业微信按钮，浏览器会先跳到企业微信的授权页面，提示“xxx应用正在申请获取你的身份信息”，点击同意后自动跳回GitPuk。第一次授权时，GitPuk会自动创建一个新用户，并给该用户一个默认角色。如果你在后台开启了自动注册，那么这一步不需要管理员干预。
如果跳转后停在空白页或者报错，立刻去服务端看两条信息：一是GitPuk容器日志，二是浏览器地址栏的URL参数。通常失败时地址栏会保留error=access_denied或code=xxx，控制台也会打出异常堆栈。把这两份信息贴到故障排查工具里，基本能定位是哪一侧配置有问题。我在测试环境第一次跑通时，发现回调地址末尾少了一个斜杠，改掉后马上就好了。
4. 核心机制拆解：一次扫码登录背后的流程
配置跑通之后，我建议你花十分钟理解一下背后的流程。很多后续排查问题，只要知道是哪一步失效，答案就出来了。这个机制其实就是标准的OAuth2授权码模式，只是企业微信把它包装成了扫码或点击授权。
4.1 授权码模式（Authorization Code）的完整链路
整个链路可以分成五步。第一步，用户访问GitPuk登录页并点击“企业微信登录”，GitPuk构造一个授权链接，链路指向企业微信的/cgi-bin/authorize接口，同时带上redirect_uri、corpid、agentid和response_type=code等参数。第二步，企业微信检查用户登录态，弹出授权确认页，用户同意后把浏览器重定向回redirect_uri，并在URL上附加一个一次性授权码code。第三步，GitPuk用这个code加上Secret去调用企业微信的/cgi-bin/gettoken接口，换取访问令牌access_token。第四步，用access_token调用/cgi-bin/auth/getuserinfo，拿到该用户在企业的唯一userid。第五步，GitPuk拿这个userid去本地数据库查找或创建对应用户，创建会话并跳转回首页。
这像一个小区门禁流程：企业微信是保安，确认你住在这个小区后，给你一张临时访客单（code），GitPuk拿着访客单去找保安换你的身份证复印件（userid），然后认你是谁，发一张门禁卡（session）给你。虽然往返多次，但每一次校验都有明确目的，安全性也有保证。
4.2 用户映射与自动注册
企业微信返回的userid是全局唯一的，但格式可能跟GitPuk自带的用户名完全不同。为了让两套体系共存，GitPuk默认会生成一个内部用户名，比如wecom_zhangsan，并在数据库里记录“这个用户名对应的企业微信userid是什么”。后续每次该用户登录，都用userid直接找到本地用户，不会再重新创建。
自动注册是我们要不要开启的选项。开启后，只要企业微信成员能通过OAuth认证，GitPuk就自动为其创建账号，不需要管理员预建。对于中小团队，这个体验最顺滑。但如果团队里有一些外包或临时人员，你希望先审核再放行，那就关闭自动注册，让首次登录提示“联系管理员绑定账号”，管理员在用户管理中将该成员与已有账号绑定即可。两种模式各有适用场景，我建议内部正式员工全量开启，外部合作方单独走审批。
4.3 权限模型与项目角色绑定
认证通过不等于拥有仓库权限，这一点要特别提醒。企业微信登录只是解决了“你是谁”的问题，GitPuk的仓库访问权限仍按项目维度分配。新创建的用户默认是普通成员，只有管理员可以在后台把它提升为Owner或Admin，或者把它拉进不同项目组。如果你希望按部门自动授权，需要依赖4.4节讲的组织架构同步能力。
这里我在实操中踩过一个坑：给企业微信域名的管理员分组时，误以为所有企微管理员应该都变成GitPuk管理员，结果把好几个人直接给成了Admin权限。安全审计时发现普通业务骨干也可以操作后台，非常不合适。最稳妥的权限策略是：默认用户只有查看自己项目的权限，管理员单独指定，部门负责人按需提升为项目Owner。
4.4 组织架构同步的延伸思路
统一认证搞定后，你可能会想，项目权限能不能也按企业微信部门自动分？可以的。企业微信通讯录API提供了部门列表、成员详情、标签等接口，只要拿到access_token，就能拉取全量组织架构。GitPuk如果支持外部用户组导入，就可以定时执行一个同步脚本，把企业微信部门映射成GitPuk团队，再把部门成员自动加入团队。
这个脚本不一定要写在GitPuk里，可以用任何语言实现。最简单的做法是：每小时跑一次任务，调用企业微信侧获取部门成员的接口，对比GitPuk现有用户组，新增缺失的用户，移除离职员工。我见过有人用十来行Python脚本加crontab就完成了同步，效果非常稳定。这个方案不需要在GitPuk内部做任何代码改动，对只想统一账号体系的团队来说，已经比手工维护用户列表省力太多了。
5. 常见问题与排查技巧实录
配置过程中，总会遇到一些意料之外的报错。我把自己和被帮助团队遇到的高频问题整理成速查，你可以直接对号入座。绝大多数问题不是GitPuk本身bug，而是企业微信后台参数没对齐。
5.1 redirect_uri不匹配导致的登录失败
浏览器跳转后如果显示“redirect_uri参数错误”或“该回调域名不在白名单中”，第一反应是检查GitPuk构造的回调地址到底带没带正确的域名。常见有三个原因：一是GITPUK_EXTERNAL_URL被配成了http://localhost:3000，导致回调地址变成http://localhost:3000/auth/wecom/callback，企业微信自然不认；二是可信域名填成了带https://的写法，后台校验不通过；三是回调地址末尾有斜杠，https://git.example.com/auth/wecom/callback/和没有斜杠的版本被视为不同地址。
排查方式是打开浏览器开发者工具，在网络请求里找到发起OAuth跳转的那条请求，复制完整的redirect_uri参数，然后和企业微信后台的“可信域名”做逐字符比对。只要这里完全一致，问题基本解决。
5.2 一直报“企业微信账号未绑定”或“未注册”
这种报错说明OAuth握手本身成功了，但GitPuk在本地用户表里没有找到匹配的用户，且自动注册被关闭了。解决方法是先确认WECOM_AUTO_CREATE_USER是否开启，我习惯把自动注册打开，然后再单独处理外包成员。如果必须要保留关闭状态，可以到GitPuk管理后台手动创建一个用户，并绑定该企业微信成员的userid。
还有一种相近情况是，用户之前用邮箱注册过GitPuk，现在想把这个账号和企业微信userid关联。找一个有Admin权限的账户，在用户管理界面点击“绑定企业微信”，输入企微返回的userid即可。注意：这个绑定过程只有在用户第一次授权后才能拿到userid，所以如果你不确定用户的userid，可以先让他在登录页点一次企业微信登录，即使因为没绑定而失败，后台日志里也会打印出userid。
5.3 内网自测流程不通的几个排查点
很多人问能不能在公司内网里先联调，答案是不行。因为企业微信的OAuth回调是云端服务器主动向你的redirect_uri发请求，而不是你本地浏览器直接访问回调。企业微信服务器必须通过公网找到你的GitPuk，内网IP地址对它来说不可达。所以本地自测时，你得用一个公网可达的域名先把请求转发到内网服务，或者在云主机上做临时环境。
如果你没有公网环境，可以退一步：先把企业微信的授权参数填好，但用Postman手动调用gettoken和getuserinfo接口，验证CorpID、AgentId、Secret是否有效。OAuth完整流程则在部署到公网后再验证。很多参数错误通过直接调用企业微信接口就能提前发现，没必要一开始就纠结回调。
5.4 让日志说话：配置日志级别与观察请求
遇到问题时，我第一件事永远是开debug日志。GitPuk启动时设置GITPUK_LOG_LEVEL=debug，重启容器后重新触发登录，然后观察容器标准输出。debug日志会把每次OAuth回调收到的code、请求企业微信接口的URL以及错误响应都打印出来。
比如日志里出现wecom gettoken failed: errcode=40013, errmsg=invalid corpid，说明CorpID填错了；出现errcode=60020，说明出口IP没白名单；出现errcode=40062，可能是AgentId和Secret不匹配。把这些错误码放到企业微信开发文档里搜一下，比自己瞎猜快得多。我习惯在故障现场直接执行docker compose logs -f --tail=200 gitpuk，同时让同事再点一次登录，这样既能看时间线又能对上下文，比看单张静态截图有用得多。
最后分享一个我自己的习惯：每次部署GitPuk并接入企业微信后，我都会先把日志级别调成debug，跑通一次登录，再把日志级别调回info。这样既留下了排查线索，又不会在正常运行时刷屏。如果你也准备在团队里做统一认证，别急于把自动注册开到底，先让三个人内测一次，确认回调稳定了再全员放开。这套流程本身不复杂，真正花时间的往往是参数对齐和权限设计。等你在企业微信后台和GitPuk之间把这条链路理顺，后面节省的是整个团队的人力，绝对值回投入。
