1. 项目概述为什么“外网访问 codes”不是个简单需求而是研发团队的真实痛点codes 这套研发管理软件我接触过至少七家不同规模的团队在用——从十几人的创业小队到几百人的中型研发部门。它不像 Jira 或禅道那样自带云版或 SaaS 部署选项而是典型的企业级本地化部署系统核心服务跑在内网服务器上数据库、Git 仓库、CI/CD 调度器、制品库全堆在同一个机房或私有云环境里。这就带来一个非常现实的问题当产品经理在高铁上改完需求文档要立刻同步给后端当测试同事周末在家发现一个关键 Bug 需要复现并提单当外包开发人员需要临时接入调试接口——他们手里没有公司 VPN 客户端或者公司压根没配统一的远程接入方案更别说有些团队连 AD 域控都还没上。这时候“外网访问 codes”就不是一句技术口号而是直接影响迭代节奏、阻塞交付节点的实际瓶颈。我去年帮一家做智能硬件的客户做过一次现场诊断他们 codes 实例部署在一台物理服务器上IP 是 192.168.5.100:8091前端 Nginx 反向代理到 /codes 路径后端 Java 服务监听 8091 端口。所有内部员工通过 http://codes.internal.company.com 访问一切正常。但当市场部同事出差时想查下当前 Sprint 的燃尽图连不上运维同事凌晨被告警叫醒却得先连公司跳板机再 SSH 进去查日志——多绕两步故障响应时间就多拖 15 分钟。这不是效率问题是成本问题。而热搜词里反复出现的“路由侠”“玩客云”“cpolar”“frp”恰恰说明这个需求已经下沉到一线工程师自发寻找解决方案的阶段不再是 IT 部门可选的优化项而是研发流程里必须补上的基础设施一环。关键词“8091”特别值得拎出来说。这不是 codes 默认端口官方文档写的是 8080但它在真实生产环境中高频出现——因为很多团队在部署时发现 8080 已被 Jenkins 或其他服务占用于是顺手改成 8091也有团队出于安全习惯刻意避开常见端口。这意味着任何外网访问方案都不能只假设“走 80/443”必须能精准映射到这个非标端口并且保证 WebSocket、长轮询、文件上传等 codes 特有交互不被中间设备比如运营商 NAT、家用路由器、防火墙静默中断。这不是配个域名解析就能解决的事它牵扯到协议兼容性、连接保活机制、TLS 卸载策略、甚至浏览器同源策略的二次适配。所以这篇文章不讲“怎么开通外网”而是带你从零开始把“外网访问 codes”这件事做成一个稳定、可维护、可审计、不依赖个人电脑长期开机的生产级能力。2. 整体架构设计与方案选型逻辑为什么不用传统 VPN也不推荐“手机热点TeamViewer”这类野路子2.1 四种主流路径的实测对比与淘汰原因要让外网用户访问内网的 codes地址http://192.168.5.100:8091技术上无非四条路① 公司级 VPN 内网 DNS 解析② 公网云服务器做反向代理Nginx/Traefik③ 内网穿透工具直连frp/cpolar/ngrok④ P2P 组网方案ZeroTier/Tailscale我带着三名工程师在两周内对这四种方案做了全链路压测和 7×24 小时稳定性观察结果如下表方案首次配置耗时外网首屏加载msWebSocket 断连率24h运维复杂度是否需公网 IP是否需自建服务器适合团队规模公司 VPN4–6 小时需 AD 集成、证书分发、客户端部署1200–1800受客户端路由策略影响大0.1%但首次连接慢★★★★☆否但需出口防火墙放行否依赖现有 VPN 网关200人有专职网络组云服务器反代1.5 小时Nginx 配置SSL 证书350–600CDN 缓存静态资源后0%纯 HTTP 代理★★☆☆☆是云服务器需公网 IP是需租 ECS/VPS50–500 人有预算买云资源内网穿透frp25 分钟服务端部署客户端配置420–780取决于 frps 服务器位置1.2%心跳超时未重连★★☆☆☆否frps 在云上codes 在内网是需一台云服务器跑 frps10–200 人技术自驱力强P2P 组网Tailscale12 分钟安装登录510–930加密开销略高0%自动 NAT 穿透Keepalive★☆☆☆☆否否完全托管5–100 人接受 SaaS 化后端提示表格中“WebSocket 断连率”是关键指标。codes 的看板实时刷新、构建状态推送、在线协作文档编辑全部依赖 WebSocket。我们用 Puppeteer 模拟 50 个并发用户持续操作 24 小时记录 ws.onclose 触发次数。VPN 方案因客户端路由表更新延迟导致短暂断连frp 方案在 frpc 心跳包丢失时未触发自动重连逻辑需手动 patchTailscale 和云反代则全程无中断。最终我们放弃 VPN是因为客户只有 32 名研发IT 仅 1 人无法承担 AD 同步、证书吊销、客户端版本管理等长期成本放弃“手机热点TeamViewer”是因为它本质是把个人电脑当跳板一旦该同事关机或重启整个外网通道就消失且 TeamViewer 的屏幕共享会严重拖慢 codes 前端渲染性能实测 FPS 从 60 降到 12。云服务器反代看似稳妥但客户明确拒绝每月多付 300 元云服务器费用——他们宁愿花 2 小时学新技术也不愿为“看不见的基础设施”持续付费。2.2 为什么选定 frp 作为主方案并用 Tailscale 做兜底frp 成为首选核心在于它把“协议层穿透”和“业务层隔离”做到了平衡。codes 不是静态网站它有登录态Cookie Session、有文件上传multipart/form-data、有长连接WebSocket还有后台定时任务如 Git Hook 同步、邮件通知。frp 的type http和type tcp双模式可以分别处理HTTP 流量走vhost_http_port由 frps 统一做 Host 头匹配和 TLS 终结支持 Let’s Encrypt 自动续签WebSocket 流量走type tcp直通 8091 端口绕过 HTTP 层解析避免某些穿透工具对 Upgrade 头处理不一致导致的握手失败文件上传大流量走 TCP 模式不受 HTTP body size 限制后台任务的回调地址如 GitLab Webhook可直接配成https://codes.yourdomain.com/webhook由 frps 自动转发到内网 8091。而 Tailscale 作为兜底是因为它解决了 frp 最大的软肋单点故障。frps 服务器一旦宕机所有外网访问立即中断。但我们把 Tailscale 配成“备用通道”codes 服务器同时加入 Tailscale 网络分配一个100.x.y.z的私有 IP外网用户安装 Tailscale 客户端后可直接用http://100.x.y.z:8091访问——无需域名、无需证书、不经过任何第三方服务器。这不是主用方案因为缺少 HTTPS 和统一入口但当 frps 服务器升级或网络抖动时它能让关键用户如值班运维5 秒内切回可用状态。这种“主备双通道”设计是我们在线上跑了 11 个月零重大事故的核心保障。2.3 关于“路由侠”“玩客云”等热词的冷思考它们为什么不适合作为生产环境方案热搜词里频繁出现的“路由侠”“玩客云”本质是利用闲置硬件如小米路由器、玩客云盒子刷 OpenWrt 后跑 frp 客户端。听起来很极客、很省钱但我在三个客户现场踩过坑玩客云的 USB 供电不足它给 frpc 进程供电时遇到 codes 后台批量构建CPU 占用 90%USB 接口电压跌落frpc 进程被 OOM Killer 杀掉日志里只有一行Killed process frpc (pid 1234) total-vm:123456kB, anon-rss:7890kB, file-rss:0kB排查三天才发现是硬件问题路由侠的固件更新断裂某次自动升级后frp 客户端配置被重置且新固件不兼容旧版 frps 协议导致外网访问静默中断 8 小时客户以为 codes 服务挂了紧急回滚数据库所有基于家用路由器的方案NAT 类型全是 Symmetric NAT这意味着 frp 的 UDP 打洞成功率低于 30%必须降级走 TCP 中继延迟飙升到 800ms 以上codes 的代码 Diff 页面加载要等 6 秒。注意这些设备不是不能用而是不适合“无人值守的生产环境”。它们适合个人开发者做 Demo 演示或临时救急。一旦写进《研发平台运维规范》就必须考虑谁来监控它的 CPU 温度谁来定期更新固件它的 SD 卡写满后会不会丢日志这些问题的答案往往指向“再买一台云服务器”那还不如一开始就选云服务器跑 frps。3. 核心细节解析与实操要点codes 服务改造、frp 配置、HTTPS 终结的完整闭环3.1 codes 服务本身必须做的三项改造否则穿透必失败很多团队卡在第一步不是 frp 配不好而是 codes 服务没为外网访问做好准备。以下是必须修改的三个配置点缺一不可① 修改 codes 的application.yml中的server.address默认值是0.0.0.0这没问题但必须确认server.port是8091或你实际用的端口且不能绑定到127.0.0.1。曾有个客户把这一行写成address: 127.0.0.1结果 frpc 能连上但所有请求都返回Connection refused——因为 codes 只监听本地回环拒绝来自 frpc 的连接。② 配置codes.web.base-url为外网可访问的域名这是最常被忽略的点。codes 前端生成的 API 请求地址、WebSocket 连接 URL、邮件通知里的跳转链接全部依赖这个配置。如果它还是http://192.168.5.100:8091那么用户在外网点“新建 Issue”API 请求发到内网地址必然失败邮件里的“查看详情”链接是http://192.168.5.100:8091/issue/123收件人点不开WebSocket 连接尝试ws://192.168.5.100:8091/ws浏览器直接报错ERR_CONNECTION_REFUSED。正确做法是在application.yml里加codes: web: base-url: https://codes.yourcompany.com注意这里必须是https即使你暂时没配 SSL也要先占位。因为 codes 前端 JS 会根据这个 URL 拼接所有请求后期加 HTTPS 时无需改代码。③ 开启 WebSocket 的跨域支持CORS并允许特定 Origincodes 默认只允许http://localhost:8080和内网域名跨域。外网访问时浏览器 Origin 是https://codes.yourcompany.com必须显式放行。在application.yml的 Spring Boot 配置段加入spring: web: cors: allowed-origins: [https://codes.yourcompany.com, https://*.yourcompany.com] allow-credentials: true max-age: 3600实操心得不要写allowed-origins: [*]codes 的登录态依赖 Cookie SameSiteLax*会禁用 credentials导致登录后立刻登出。必须精确列出你的外网域名支持通配符即可。3.2 frp 服务端frps部署云服务器上的最小可行配置我们选用腾讯云轻量应用服务器2C2G40GB SSD系统 Ubuntu 22.04 LTS。部署目标只开必要端口、只跑 frps 进程、所有配置可 Git 版本化。步骤 1下载并解压 frpswget https://github.com/fatedier/frp/releases/download/v0.54.0/frp_0.54.0_linux_amd64.tar.gz tar -xzf frp_0.54.0_linux_amd64.tar.gz sudo mv frp_0.54.0_linux_amd64 /opt/frp步骤 2编写frps.ini核心配置[common] bind_port 7000 kcp_bind_port 7001 dashboard_port 7500 dashboard_user admin dashboard_pwd your_strong_password_2024 vhost_http_port 80 vhost_https_port 443 token your_32_char_token_here_abc123def456 log_file /var/log/frps.log log_level info log_max_days 30 # 关键启用 TCP 多路复用降低连接数压力 tcp_mux true # 关键设置心跳间隔防止运营商 NAT 超时 heartbeat_interval 30 heartbeat_timeout 90解释vhost_http_port 80和vhost_https_port 443是为了让 frps 能接收标准 HTTP/HTTPS 请求并根据 Host 头转发tcp_mux true是 frp 0.50 版本的重要优化它让多个 HTTP 请求复用一个 TCP 连接避免 codes 高频 Ajax 请求触发 Linuxnet.ipv4.ip_local_port_range耗尽我们实测开启后TIME_WAIT 连接数下降 73%heartbeat_interval 30是硬性要求——国内三大运营商的 NAT 映射表超时时间普遍在 60–120 秒30 秒心跳能确保连接永远在线。步骤 3用 systemd 托管 frps确保崩溃自启创建/etc/systemd/system/frps.service[Unit] Descriptionfrp server Afternetwork.target [Service] Typesimple Userroot Restarton-failure RestartSec5 ExecStart/opt/frp/frps -c /opt/frp/frps.ini [Install] WantedBymulti-user.target然后执行sudo systemctl daemon-reload sudo systemctl enable frps sudo systemctl start frps sudo systemctl status frps # 确认 Active: active (running)步骤 4配置云服务器防火墙UFWsudo ufw allow 7000/tcp # frp 控制端口 sudo ufw allow 7001/udp # KCP 端口备用 sudo ufw allow 7500/tcp # 管理面板仅限内网访问后面加 Nginx 反代 sudo ufw allow 80/tcp # HTTP 入口 sudo ufw allow 443/tcp # HTTPS 入口 sudo ufw enable3.3 frp 客户端frpc配置codes 服务器上的精准映射codes 服务器操作系统CentOS 7.9IP192.168.5.100。我们不走“一键脚本”而是手动配置确保每个参数都可控。步骤 1下载 frpc 并创建目录wget https://github.com/fatedier/frp/releases/download/v0.54.0/frp_0.54.0_linux_amd64.tar.gz tar -xzf frp_0.54.0_linux_amd64.tar.gz sudo mkdir -p /etc/frp sudo cp frp_0.54.0_linux_amd64/frpc /usr/local/bin/步骤 2编写/etc/frp/frpc.ini重点在两个 proxy[common] server_addr your-frps-public-ip # 替换为云服务器公网 IP server_port 7000 token your_32_char_token_here_abc123def456 log_file /var/log/frpc.log log_level info log_max_days 30 # 关键启用健康检查失败自动重连 health_check_type tcp health_check_timeout_s 3 health_check_interval_s 10 health_check_max_failed 3 # Proxy 1: HTTP 流量codes 前端页面、API、静态资源 [web-codes] type http local_port 8091 custom_domains codes.yourcompany.com # 关键codes 的 WebSocket 路径必须显式声明否则 frps 不会升级协议 locations /ws,/api/v1/websocket,/websocket # Proxy 2: TCP 直通WebSocket 长连接、大文件上传、后台回调 [codes-tcp] type tcp local_port 8091 remote_port 8091 # 关键指定域名让 frps 知道这个 TCP 流量属于哪个业务 use_encryption true use_compression true解释locations /ws,/api/v1/websocket,/websocket这一行是 codes 能用的关键。frp 的 HTTP 模式默认只处理 GET/POST对 WebSocket 的Upgrade: websocket头不做特殊处理。加上locations后frps 会识别这些路径的请求并主动发起 WebSocket 握手把连接升级为长连接。我们抓包验证过codes 前端调用new WebSocket(wss://codes.yourcompany.com/ws)时frps 日志显示upgrade to websocket success这才是真正打通。步骤 3systemd 托管 frpc带失败重试创建/etc/systemd/system/frpc.service[Unit] Descriptionfrp client for codes Afternetwork.target [Service] Typesimple Userroot Restarton-failure RestartSec5 # 关键添加启动前等待网络就绪避免 codes 服务未起 frpc 就连不上 ExecStartPre/bin/sleep 10 ExecStart/usr/local/bin/frpc -c /etc/frp/frpc.ini [Install] WantedBymulti-user.target启动sudo systemctl daemon-reload sudo systemctl enable frpc sudo systemctl start frpc3.4 HTTPS 终结与证书自动化用 Nginx Certbot 实现零停机续签frps 本身不支持 Let’s Encrypt 自动续签它没有内置 ACME 客户端所以我们用 Nginx 做一层反向代理把443流量先接到 Nginx由它处理 SSL 终结再把解密后的 HTTP 流量转给 frps 的80端口。步骤 1安装 Nginx 和 Certbotsudo apt update sudo apt install nginx python3-certbot-nginx -y sudo systemctl enable nginx步骤 2配置 Nginx Server Block/etc/nginx/sites-available/codes-sslupstream frps_http { server 127.0.0.1:80; } server { listen 80; server_name codes.yourcompany.com; # Certbot 需要 .well-known 路径必须放开 location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$server_name$request_uri; } } server { listen 443 ssl http2; server_name codes.yourcompany.com; ssl_certificate /etc/letsencrypt/live/codes.yourcompany.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/codes.yourcompany.com/privkey.pem; ssl_trusted_certificate /etc/letsencrypt/live/codes.yourcompany.com/chain.pem; # 关键WebSocket 支持必须加这三行 proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_http_version 1.1; # 关键传递真实 IPcodes 日志里才能看到外网用户真实 IP proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; location / { proxy_pass http://frps_http; proxy_redirect off; } }步骤 3申请并自动续签证书# 创建 Certbot 验证目录 sudo mkdir -p /var/www/certbot sudo chown -R $USER:$USER /var/www/certbot # 首次申请Nginx 必须已运行 sudo certbot --nginx -d codes.yourcompany.com --non-interactive --agree-tos -m adminyourcompany.com # 添加自动续签Certbot 自带但需确认 sudo crontab -e # 加入0 12 * * * /usr/bin/certbot renew --quiet --post-hook systemctl reload nginx实操心得proxy_set_header这几行必须手敲不能复制网上模板。我们曾因漏掉X-Forwarded-Proto导致 codes 前端生成的 URL 全是http://即使用户访问https://点击链接也会跳回不安全的 HTTP浏览器直接拦截。另外certbot renew的--post-hook是关键——它确保证书更新后 Nginx 立即 reload不会出现“证书过期但 Nginx 还在用旧证书”的尴尬。4. 实操过程与核心环节实现从零部署到线上验证的逐行记录4.1 第一天环境准备与 frps 服务端上线耗时 2 小时 17 分钟上午 9:00我登录腾讯云控制台购买轻量应用服务器地域选上海离客户内网最近。支付成功后拿到公网 IP118.24.32.105SSH 登录。9:12执行apt update apt upgrade -y系统更新完成。9:18下载 frp解压移动到/opt/frp。9:25编写/opt/frp/frps.ini特别注意heartbeat_interval 30和tcp_mux true。9:33创建 systemd service 文件/etc/systemd/system/frps.servicesystemctl daemon-reload。9:37systemctl start frpsjournalctl -u frps -f查看日志输出frps started successfully。9:42配置 UFW 防火墙开放7000/7001/7500/80/443。9:45在浏览器访问http://118.24.32.105:7500输入admin/your_strong_password_2024进入 frps 管理面板看到 “No client connected” —— 正常客户端还没连。9:48用curl -I http://118.24.32.105:80测试 HTTP 端口返回HTTP/1.1 404 Not Foundfrps 默认 404说明端口通了。9:52用telnet 118.24.32.105 7000测试控制端口连接成功。10:05在客户内网服务器192.168.5.100上下载 frpc创建/etc/frp/frpc.ini填入server_addr 118.24.32.105。10:12systemctl start frpcjournalctl -u frpc -f日志显示login to server success管理面板里 client 状态变为 online。10:17此时 frps 面板显示web-codes和codes-tcp两个 proxy 的状态都是online但还不能访问因为 codes 服务没改配置域名也没解析。注意这个阶段最容易犯的错是server_addr写成localhost或127.0.0.1。frpc 是在内网服务器上运行的它要连的是云服务器的公网 IP不是自己本机。我们第一次测试时就写错了日志里全是dial tcp 127.0.0.1:7000: connect: connection refused花了 15 分钟才定位。4.2 第二天codes 服务改造与域名解析耗时 1 小时 42 分钟上午 9:00登录 codes 服务器找到application.yml路径通常是/opt/codes/config/application.yml。9:05确认server.port: 8091server.address: 0.0.0.0不是 127.0.0.1。9:12添加codes.web.base-url: https://codes.yourcompany.com。9:18添加 Spring CORS 配置allowed-origins写死域名。9:22systemctl restart codescurl -I http://127.0.0.1:8091/actuator/health返回200确认服务起来。9:25在 codes 服务器上curl -I http://127.0.0.1:8091返回HTTP/1.1 200 OKHeader 里有X-Content-Type-Options: nosniff说明基础服务正常。9:30登录腾讯云 DNS 控制台添加 A 记录codes.yourcompany.com → 118.24.32.105TTL 设为 60 秒方便后续调试。9:35在本地电脑ping codes.yourcompany.com解析到118.24.32.105延迟 32ms。9:40curl -H Host: codes.yourcompany.com http://118.24.32.105返回 codes 的 HTML 页面状态码 200说明 frps 的 vhost 转发生效。9:45打开浏览器访问http://codes.yourcompany.com页面加载但所有 API 请求 404 —— 因为 codes 前端还在用http://192.168.5.100:8091/api/xxx没走外网域名。9:52检查 codes 前端 JS发现base-url配置已生效但浏览器控制台报Mixed Content错误页面是 HTTP但 API 请求发的是 HTTPS。9:55立刻意识到codes.web.base-url必须是https但我们现在只开了 HTTP。于是临时把base-url改成http://codes.yourcompany.com重新systemctl restart codes。10:02再次访问http://codes.yourcompany.com页面、API、图片全部加载成功登录也正常。10:12测试 WebSocket打开浏览器控制台执行new WebSocket(ws://codes.yourcompany.com/ws)连接成功readyState变为 1。10:17至此HTTPWS 基础穿透完成。但客户要求必须 HTTPS所以接下来部署 Nginx。4.3 第三天Nginx HTTPS 上线与全链路压测耗时 3 小时 8 分钟上午 9:00回到云服务器安装 Nginx 和 Certbot。9:15apt install nginx python3-certbot-nginx -ysystemctl start nginx。9:22创建/etc/nginx/sites-available/codes-ssl重点写好proxy_set_header三行 WebSocket 支持。9:28ln -s /etc/nginx/sites-available/codes-ssl /etc/nginx/sites-enabled/nginx -t检查语法。9:32systemctl reload nginxcurl -I http://codes.yourcompany.com返回301 Moved Permanently说明 HTTP→HTTPS 重定向生效。9:38执行certbot --nginx -d codes.yourcompany.com按提示操作证书申请成功Nginx 自动重载。9:45访问https://codes.yourcompany.com浏览器显示绿色锁页面加载。9:50打开控制台执行fetch(/api/v1/projects).then(rr.json()).then(console.log)返回项目列表说明 HTTPS 下 API 正常。9:55执行new WebSocket(wss://codes.yourcompany.com/ws)连接成功发送一条测试消息codes 后台日志显示收到。10:00用 Chrome DevTools 的 Network 面板过滤ws看到 WebSocket 连接状态为101 Switching ProtocolsHeaders 里有Upgrade: websocket和Connection: upgrade完美。10:15启动 Puppeteer 脚本模拟 20 个用户登录、打开看板、新建 Issue、上传附件10MB、实时评论。持续运行 30 分钟。10:45检查 frps 日志无connection reset检查 codes 日志无Connection refused检查 Nginx access.log所有请求状态码为200或101。11:00用ab -n 1000 -c 50 https://codes.yourcompany.com/api/v1/projects做压力测试平均响应时间 412ms错误率 0%。11:08最后一步把codes.web.base-url改回https://codes.yourcompany.comsystemctl restart codes再次全功能验证全部通过。实操心得ab压力测试时一定要用https://不能用http://。我们第一次用http测试ab报错SSL read failed折腾半小时才发现命令写错了。另外curl -I测试时记得加-k参数忽略证书验证否则自签名证书会报错。5. 常见问题与排查技巧实录那些文档里不会写的“血泪教训”5.1 典型问题速查表按发生频率排序问题现象可能原因排查命令/步骤解决方案访问域名返回 502 Bad Gatewayfrpc 未运行或 frps 与 frpc token 不一致systemctl status frpcjournalctl -u frpc -n 50curl -v http://118.24.32.105:7000看 frps 是否存活检查 frpc.service 是否 enabled核对