github-for-jira 对接 GitHub Enterprise Server：Nginx 反向代理部署实战（附完整配置）-平芜编程栈

github-for-jira 对接 GitHub Enterprise Server：Nginx 反向代理部署实战（附完整配置）

【免费下载链接】github-for-jiraDEPRECATED (moved to private repository) - Connect your code with your project management in Jira项目地址: https://gitcode.com/gh_mirrors/gi/github-for-jira

github-for-jira 是 Atlassian 开源维护的官方集成工具，用于把 GitHub 代码与 Jira 项目管理无缝连接。当企业使用部署在内网的GitHub Enterprise Server（GHE）时，云端 Jira 无法直接访问内网地址，此时通过Nginx 反向代理即可安全打通双方通信。本文将基于官方示例 docs/sample-reverse-proxy-nginx.conf 逐段拆解配置，带你完成一次可落地的反向代理部署实战。

为什么需要 Nginx 反向代理打通 GHE 与 Jira Cloud？

Jira Cloud 运行在 Atlassian 的云端服务器上，而 GitHub Enterprise Server 通常部署在公司内网，两者之间存在两个核心障碍：

网络不可达：云端无法路由到内网 IP，需要一台公网可达的代理服务器作为中转。
地址与校验不一致：内网主机名、公网主机名不同，且 Jira 回调时会校验来源 IP，必须确保来自 Atlassian 的合法请求才能放行。

Nginx 反向代理恰好承担了「翻译官 + 守门员」的双重角色：对外暴露统一域名，对内转发到 GHE，同时完成请求头、响应内容中的地址改写与来源鉴权。

反向代理的工作流程：一次请求如何流转

整个代理链路可以概括为四个步骤：

Jira Cloud 向公网域名public-ghe-hostname.mycompany.com发起请求；
Nginx 校验来源 IP 是否为 Atlassian 白名单（或携带合法 API Key）；
通过校验后，代理将请求转发到内网private-ghe-hostname.intranet.local；
返回的响应中，所有内网地址会被自动替换为公网地址，Jira 才能正确识别。

这套流程在配置文件中通过map、proxy_set_header、sub_filter与 Lua 过滤器协作完成。

部署前的准备工作

开始配置前，请确认以下三件事：

使用带 Lua 模块的 Nginx（推荐 OpenResty）：配置中的header_filter_by_lua_block依赖ngx_http_lua_module，普通 Nginx 需要额外编译该模块；
准备内外网两套域名：内网域名如private-ghe-hostname.intranet.local，公网域名如public-ghe-hostname.mycompany.com，并在 DNS 中做好解析；
申请 SSL 证书：示例中预留了 443 端口监听，生产环境必须配置 HTTPS 证书（配置中已标注 TODO）。

完整 Nginx 反向代理配置详解

下面按配置文件的顺序逐段讲解，完整文件可直接参考 docs/sample-reverse-proxy-nginx.conf。

第一步：定义内网与外网主机名映射

配置开头用四个map指令定义了内网、外网的主机名与基础 URL：

map $http_host $internal_ghe_hostname { default "private-ghe-hostname.intranet.local"; } map $http_host $internal_ghe_baseurl { default "http://$internal_ghe_hostname"; } map $http_host $public_ghe_hostname { default "public-ghe-hostname.mycompany.com"; } map $http_host $public_ghe_baseurl { default "https://$public_ghe_hostname"; }

这段配置的核心作用是把「外网可见地址」与「内网真实地址」解耦。后续所有改写逻辑都引用这四个变量，后续维护只需改这一处即可。

第二步：重写 Referer 与请求头

Jira 发起请求时携带的Referer是公网地址，转发到内网后 GHE 可能因域名不匹配而拒绝。配置通过map将公网 Referer 改写为内网地址：

map $http_referer $new_referer { default $http_referer; "~^$public_ghe_baseurl(.*)$" "$internal_ghe_baseurl$1"; }

同时在location /中重写Host、Referer头，并禁用压缩以方便后续内容改写：

proxy_set_header Host $internal_ghe_hostname; proxy_set_header Referer $new_referer; proxy_set_header Accept-Encoding ""; proxy_redirect ~^($internal_ghe_baseurl)(/.*)?$ $public_ghe_baseurl$2;

第三步：Atlassian IP 白名单鉴权（安全核心）

安全是反向代理的重中之重。官方配置只允许两类来源访问：

Atlassian 官方 IP 段：104.192.138.240~255与13.52.5.96~127（在map $remote_addr $is_atlassian_ip中定义）；
公司内网 IP 段：示例为192.168.0.*，用于内部调试；
携带自定义 API Key 的请求：请求头X-MySecretHeader值与配置一致时放行。

鉴权逻辑位于location /末尾：

if ($remote_addr ~ "^(192\.168\.0\.)") { proxy_pass $internal_ghe_baseurl; break; } if ($is_atlassian_ip = 0) { return 401 "Not allowed"; } if ($http_x_mysecretheader = "MY_API_KEY") { proxy_pass $internal_ghe_baseurl; break; } return 401 "Not allowed";

任何不满足条件的请求都会被直接返回401 Not allowed，从源头杜绝非法访问。

第四步：响应内容与头部的地址改写

GHE 返回的响应中可能包含内网地址（例如Location跳转、HTML 链接），如果直接透传，Jira 将无法识别。配置采用双重改写：

响应头改写：通过 Lua 块遍历所有响应头，将内网主机名替换为公网主机名；
响应体改写：通过sub_filter将正文中的内网主机名全局替换：

sub_filter "$internal_ghe_hostname" "$public_ghe_hostname"; sub_filter_once off;

注意header_filter_by_lua_block中的 Lua 代码同时处理了字符串与数组类型的响应头，覆盖了 Cookie、Set-Cookie 等场景，这正是推荐使用 OpenResty 的原因。

安全加固与常见问题排查

部署上线后，建议再做以下加固：

更换 API Key：将MY_API_KEY改为强随机字符串，并妥善保管；
更新 IP 白名单：Atlassian 的 IP 段可能调整，建议关注官方 IP 白名单文档并及时同步；
开启 HTTPS：为 443 端口配置 TLS 证书与ssl_protocols。

常见报错与解决思路：

报错信息	可能原因	解决办法
`401 Not allowed`	来源 IP 不在白名单、Key 错误	检查请求头与来源 IP 段
`no resolver defined to resolve`	代理未配置 DNS 解析器	在`http`块启用`resolver`，填入公司 DNS（参考配置注释）
页面跳转到内网域名	`sub_filter`或 Lua 改写未生效	确认 Nginx 已加载 Lua 模块，且关闭了压缩

总结：让 Jira 与内网 GHE 稳定握手

通过这份 Nginx 反向代理配置，github-for-jira 得以在内网 GitHub Enterprise Server 与云端 Jira 之间建立一条安全、可控的通道：公网域名对外统一暴露，内网地址在代理层完成双向改写，Atlassian IP 白名单与 API Key 双保险保障安全。

对于想要快速体验的开发者，也可以先 clone 仓库获取完整配置示例：

git clone https://gitcode.com/gh_mirrors/gi/github-for-jira

然后参照 docs/sample-reverse-proxy-nginx.conf 逐项替换域名与密钥，即可在自己的环境中完成 github-for-jira 对接 GitHub Enterprise Server 的反向代理部署。

【免费下载链接】github-for-jiraDEPRECATED (moved to private repository) - Connect your code with your project management in Jira项目地址: https://gitcode.com/gh_mirrors/gi/github-for-jira

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考