内网代码托管平台自签名证书配置指南：从生成到客户端信任-北京尧图网络

1. 为什么内网环境需要自签名证书很多团队在内部网络搭建代码托管平台时都会遇到一个很实际的问题平台部署在内网没有公网域名也懒得去申请受信任的CA证书于是直接用IP加HTTP访问。短时间用着没问题但一旦涉及到账号密码传输、令牌调用、CI/CD流水线里的克隆操作HTTP明文传输就变得非常刺眼。密码在网络上裸奔任何一个能抓包的人都能看到这在安全审计里基本是一票否决项。自签名证书就是解决这个矛盾最直接的方案。它不需要向任何公共CA机构申请不需要域名备案也不需要花钱自己生成一对密钥和证书把证书装到服务端再把根证书分发给所有需要访问的客户端就能把HTTP升级成HTTPS。整个过程完全在内部闭环不依赖外部网络特别适合内网代码托管、内部测试环境、临时演示环境这类场景。但自签名证书有个绕不开的坎浏览器和Git客户端默认都不信任它。因为证书不是受信任CA签发的客户端无法验证服务端身份就会弹出安全警告Git命令行则会直接报错“SSL certificate problem: self-signed certificate”。很多人第一次配的时候看到这个报错就卡住了要么放弃改用HTTP要么直接关掉SSL验证这两种做法都不太妥当。关掉验证等于把HTTPS的安全意义完全抹掉只是换了个协议名而已。所以这篇文章要讲清楚的是怎么生成一套合理的自签名证书怎么把它正确配置到代码托管平台上怎么让浏览器和Git客户端都信任它以及在这个过程中有哪些容易踩的坑。整套流程我反复做过很多次从单机测试到小团队内部使用都跑通过下面把完整的思路和操作细节拆开来讲。2. 自签名证书的整体设计思路2.1 证书链的基本结构要理解自签名证书怎么配先得搞清楚证书链是怎么回事。正常的HTTPS证书是一条信任链根证书签发中间证书中间证书签发服务器证书客户端信任根证书就能顺着链条验证服务器证书。自签名证书相当于自己扮演了CA的角色自己生成根证书再用根证书签发服务器证书形成一条只有两级的短链。这里有个关键点服务器证书里必须包含正确的“使用者备用名称”也就是SAN。早期证书用CN字段来标识域名但现代浏览器和Git客户端已经不再依赖CN而是强制检查SAN。如果SAN里没有你访问时用的地址即使证书本身没问题客户端也会报“证书名称不匹配”。所以生成证书时SAN里要写清楚所有可能用到的访问方式包括IP地址和主机名。2.2 为什么推荐两级证书而不是单级自签名有人图省事直接生成一张自签名证书既当根证书又当服务器证书装到服务端就完事。这样做的问题是客户端要信任这张证书就得把这张服务器证书本身导入受信任列表。一旦服务器证书到期或者需要更换所有客户端都得重新导入一遍维护成本很高。更合理的做法是生成两级一张根证书长期有效只用来签发一张服务器证书短期有效装到服务端。客户端只需要信任根证书服务器证书换了也不影响客户端的信任关系。这个结构和公共CA的运作方式是一致的只是把CA换成了自己。根证书的私钥要保管好最好离线保存服务器证书的私钥放在服务端即可。2.3 证书参数的选择逻辑生成证书时有一堆参数要填很多人直接一路回车用默认值结果后面出各种问题。这里把关键参数的选择逻辑说清楚。密钥算法选RSA 2048位或4096位2048位目前足够安全4096位更稳妥但握手稍慢。椭圆曲线算法也可以但兼容性在某些老客户端上不如RSA。有效期方面根证书可以设长一些比如十年服务器证书建议不超过两年方便轮换。SAN里要写全IP和域名格式是IP:192.168.1.100和DNS:gitlab.internal这种。国家、省份、组织这些字段随便填不影响功能但建议填得规范一点方便以后排查。还有一个容易忽略的点基本约束。根证书要标记为CA:TRUE表示它可以签发其他证书服务器证书要标记为CA:FALSE表示它不能被用来签发。这个标记如果搞反了客户端验证时会直接拒绝。3. 生成自签名证书的完整操作3.1 准备目录和配置文件我习惯把所有证书相关文件放在一个独立目录里比如/etc/gitlab/ssl或者项目目录下的certs文件夹。先建目录然后创建一个OpenSSL配置文件把SAN等信息写进去避免命令行里拼一长串参数。mkdir -p /etc/gitlab/ssl cd /etc/gitlab/ssl创建openssl.cnf文件内容如下[req] default_bits 4096 prompt no default_md sha256 distinguished_name dn req_extensions req_ext [dn] C CN ST Internal L Internal O Internal Team OU Dev CN gitlab.internal [req_ext] subjectAltName alt_names [alt_names] DNS.1 gitlab.internal DNS.2 gitlab IP.1 192.168.1.100这个配置文件里CN写的是主机名alt_names里把域名和IP都列上。实际使用时把IP换成你服务器的真实内网地址。如果还有其他访问方式比如短主机名或者第二个网卡地址都加进去。3.2 生成根证书根证书的私钥要加密码保护虽然每次签发都要输密码稍微麻烦但安全上值得。命令如下openssl genrsa -aes256 -out ca.key 4096执行后会提示输入密码输两遍记住。然后生成根证书有效期设十年openssl req -new -x509 -days 3650 -key ca.key -out ca.crt \ -subj /CCN/STInternal/LInternal/OInternal Team/OUDev/CNInternal Root CA \ -extensions v3_ca这里-extensions v3_ca会应用默认的CA扩展确保根证书带有CA:TRUE标记。生成完可以用下面的命令检查一下openssl x509 -in ca.crt -text -noout | grep -A1 Basic Constraints应该看到CA:TRUE。3.3 生成服务器证书先生成服务器私钥这次不加密码因为服务端启动时没法交互输入密码openssl genrsa -out gitlab.key 4096然后生成证书签名请求openssl req -new -key gitlab.key -out gitlab.csr -config openssl.cnf再用根证书签发服务器证书有效期设两年openssl x509 -req -days 730 -in gitlab.csr -CA ca.crt -CAkey ca.key \ -CAcreateserial -out gitlab.crt -extensions req_ext -extfile openssl.cnf签发时需要输入根证书私钥的密码。完成后检查服务器证书的SANopenssl x509 -in gitlab.crt -text -noout | grep -A1 Subject Alternative Name确认里面包含你配置的所有IP和域名。同时检查基本约束应该是CA:FALSE。3.4 合并证书链有些服务端配置需要把服务器证书和根证书合并成一个文件形成完整的证书链。顺序是服务器证书在前根证书在后cat gitlab.crt ca.crt gitlab-chain.crt这样客户端在握手时能拿到完整链条验证起来更顺畅。虽然客户端本地已经信任了根证书但带上链条是更规范的做法。4. 在代码托管平台上配置HTTPS4.1 放置证书文件不同平台的配置方式略有差异但核心都是指定证书和私钥的路径。以常见的自建代码托管平台为例通常有一个专门的配置目录比如/etc/gitlab/ssl。把gitlab.crt和gitlab.key放进去权限设为600属主设为服务运行用户chmod 600 gitlab.key chown git:git gitlab.key gitlab.crt权限这块很多人不注意私钥文件如果其他用户可读等于把钥匙挂在门上。600权限是底线有些安全要求高的环境还会用700目录权限再加一层。4.2 修改服务配置在平台的主配置文件里找到外部URL的配置项把http://改成https://同时指定证书路径。以某类配置文件为例external_url https://gitlab.internal nginx[ssl_certificate] /etc/gitlab/ssl/gitlab-chain.crt nginx[ssl_certificate_key] /etc/gitlab/ssl/gitlab.key nginx[redirect_http_to_https] trueredirect_http_to_https这个选项建议打开这样即使用户输入了http地址也会自动跳转到https避免有人误用明文访问。改完配置后重新加载服务gitlab-ctl reconfigure这个命令会重新生成Nginx配置并重启相关服务第一次执行时间稍长耐心等它跑完。4.3 验证服务端配置服务起来后先用curl在服务器本机测试curl -v --cacert /etc/gitlab/ssl/ca.crt https://gitlab.internal如果返回正常的HTML内容说明服务端证书配置没问题。如果报错看具体错误信息证书链不完整、私钥不匹配、SAN不包含访问地址这几种是最常见的。也可以用openssl直接测试握手openssl s_client -connect gitlab.internal:443 -CAfile /etc/gitlab/ssl/ca.crt输出里会显示证书链和验证结果Verify return code: 0 (ok)表示验证通过。5. 让客户端信任自签名证书5.1 浏览器端导入根证书浏览器不信任自签名证书需要把根证书ca.crt导入到系统的受信任根证书列表。不同操作系统操作方式不同但思路一致找到“受信任的根证书颁发机构”这个存储区导入ca.crt导入时确认信任该证书用于识别网站。导入后重启浏览器再访问平台地址地址栏应该显示锁标志不再有安全警告。如果还有警告检查导入的位置是否正确有时候导入到了“个人”存储区而不是“受信任的根证书颁发机构”就不会生效。5.2 Git客户端配置Git客户端默认使用系统的证书存储但不同平台和不同Git发行版行为有差异。最稳妥的方式是显式告诉Git使用我们指定的根证书git config --global http.sslCAInfo /path/to/ca.crt这个配置对所有HTTPS仓库生效。如果只想对特定域名生效可以用git config --global http.https://gitlab.internal/.sslCAInfo /path/to/ca.crt配置完后测试克隆git clone https://gitlab.internal/group/project.git如果还报SSL错误用GIT_CURL_VERBOSE1环境变量跑一次看详细的握手过程能定位到具体是哪一步失败。5.3 命令行工具的证书配置除了Git其他命令行工具也可能需要访问平台比如CI/CD里的runner、自动化脚本里的curl调用。curl可以用--cacert参数指定根证书也可以把根证书放到系统默认的CA目录里。Linux下通常是/usr/local/share/ca-certificates/放进去后执行update-ca-certificates更新。这样系统层面的工具都能信任这张根证书不用每个工具单独配。注意把自签名根证书加入系统信任列表意味着这台机器信任该根证书签发的所有证书。根证书私钥一定要保管好一旦泄露攻击者可以签发任意服务器证书来冒充内网服务。6. 常见问题与排查技巧6.1 证书验证失败的典型原因报错信息可能原因排查方法SSL certificate problem: self-signed certificate客户端未信任根证书检查根证书是否导入Git的sslCAInfo是否指向正确路径certificate has expired证书过期用openssl x509 -in cert.crt -noout -dates查看有效期certificate subject name does not matchSAN不包含访问地址检查SAN里的IP和域名是否覆盖当前访问方式unable to get local issuer certificate证书链不完整确认服务端配置的是合并后的证书链文件key values mismatch证书和私钥不配对用openssl rsa -noout -modulus和openssl x509 -noout -modulus对比模数6.2 证书更换后的处理服务器证书到期更换后客户端不需要做任何操作因为信任的是根证书根证书没变新签发的服务器证书自动被信任。但如果根证书也换了所有客户端都要重新导入新的根证书。所以根证书的有效期要设得足够长减少更换频率。更换服务器证书时把新的证书和私钥放到配置路径重新加载服务即可。如果用了合并的证书链文件记得重新生成。更换后可以用openssl s_client验证新证书是否生效。6.3 多台服务器共用证书如果有多台内网服务器需要配置HTTPS可以用同一张根证书签发不同的服务器证书每台服务器证书的SAN里写各自的地址。这样客户端只需要信任一张根证书就能访问所有服务器。管理起来比每台服务器单独生成自签名证书要清爽得多。也可以给每台服务器签发包含多个SAN的证书但这样一张证书泄露影响面更大不推荐。按服务器分开签发各自独立更符合最小权限原则。6.4 容器环境下的证书处理在容器里跑Git客户端或者CI runner时容器内可能没有宿主机的证书存储。解决办法是在构建镜像时把根证书复制进去并更新CA存储或者运行时把根证书挂载到容器里再配置Git使用它。Dockerfile里可以这样写COPY ca.crt /usr/local/share/ca-certificates/internal-ca.crt RUN update-ca-certificates这样容器内的Git和curl都能信任自签名证书。如果容器基础镜像没有update-ca-certificates命令可以手动把证书追加到/etc/ssl/certs/ca-certificates.crt文件末尾。7. 实操中的经验与避坑要点7.1 私钥权限和备份私钥文件的权限一定要严格控制600是底线。我见过有人把私钥放在Web可访问目录里结果被扫描到直接下载走等于把HTTPS的底裤都扒了。根证书私钥最好离线保存不要放在服务器上签发服务器证书时临时拷过来用用完删掉。备份方面根证书和私钥要备份服务器证书和私钥也要备份。但备份介质的访问权限同样要控制不能随便扔在共享目录里。我习惯把根证书私钥加密压缩后存到独立的密码管理工具里服务器证书私钥则随服务器配置一起备份。7.2 SAN配置的常见遗漏SAN里最容易漏的是短主机名。比如配置里只写了gitlab.internal但用户习惯用gitlab直接访问就会报名称不匹配。解决办法是把所有可能的访问方式都列进SAN包括完整域名、短主机名、IP地址。多写几个不影响功能漏写一个就可能导致部分用户访问失败。另一个容易漏的是IPv6地址。如果内网启用了IPv6客户端可能优先用IPv6访问而SAN里只有IPv4地址同样会报错。检查方法是用curl -6强制走IPv6测试一下。7.3 时间同步的重要性证书验证依赖系统时间如果服务器和客户端时间偏差太大会报“证书尚未生效”或“证书已过期”。内网环境如果没有配置NTP机器时间跑偏是常有的事。配置证书前先确认所有相关机器的时间是同步的可以用date命令对比偏差超过几分钟就要先校准时间。7.4 逐步替换而非一刀切如果平台已经在用HTTP运行不要直接改成HTTPS然后重启那样所有正在进行的克隆和推送都会中断。更稳妥的做法是先配好HTTPS让两种协议并行运行一段时间通知团队成员更新远程地址等所有人都切换过来后再关闭HTTP。平台配置里通常有选项可以同时监听HTTP和HTTPS利用这个过渡期平滑迁移。7.5 测试覆盖要全面配置完成后测试不能只测浏览器访问。要把所有使用场景都覆盖到浏览器访问、Git命令行克隆、CI/CD流水线拉取代码、API调用、Webhook回调。每个场景用的客户端和证书验证逻辑可能不同只测一个场景就上线很容易在某个环节翻车。我一般会列一个清单逐项打勾确认全部通过才算配置完成。8. 关于证书轮换和长期维护自签名证书不是配一次就一劳永逸的。服务器证书有有效期到期前要记得更换。我建议在日历上设个提醒提前一个月开始准备轮换。轮换流程就是重新生成服务器证书替换服务端文件重新加载服务。因为根证书没变客户端无感知整个过程可以做到零中断。根证书虽然有效期长但也不是永久的。如果根证书私钥有泄露风险或者组织架构调整需要更换CA就要走完整的根证书轮换流程。这个流程麻烦一些需要重新签发所有服务器证书并通知所有客户端导入新的根证书。所以根证书的私钥保护要格外上心避免被迫轮换。还有一点证书的算法和密钥长度也要跟上时代。现在2048位RSA还够用但过几年可能就不够了。根证书有效期设十年的话中间可能要评估一次是否升级到更长的密钥或换用椭圆曲线算法。这些都要在规划时留出余地。我个人在实际操作中的体会是自签名证书这套东西原理不复杂但细节特别多。每一个参数、每一个权限、每一个配置项都可能成为后面排查问题的线索。第一次配的时候花点时间把每个步骤都理解透后面维护起来就轻松很多。最怕的是一知半解照着教程敲一遍命令出了问题完全不知道从哪查起。把证书链的结构搞清楚把SAN的作用搞明白把客户端信任的逻辑理顺剩下的就是熟练度问题了。

内网代码托管平台自签名证书配置指南：从生成到客户端信任

相关推荐

海康网络摄像机OSD字符叠加：BCB6.0调用SDK把文字写进编码前帧缓冲

Forms-Dynamics：用结构化记忆根治RAG碎片化，打造稳定Agent长时记忆

IDEA升级后无法启动？从闪退到卡死的完整排查指南

更多资讯

PyTorch实战：猫狗图像分类从入门到部署

AI写作工具怎么选？六大平台榜单与智能改写实操指南

逆向Lua 5.1字节码：luadec51反编译实战与二次开发

open-code-review：从形式化到高效落地的Code Review实践指南

开源代码审查工具 open-code-review 实战：从 Git diff 到规则引擎

开源代码审查CLI工具：Git集成+LLM混合推理实战

今日更新

悟空开源无代码平台实战：从实体建模到应用设计避坑指南

基于.NET9的多租户权限系统：数据权限与动态API落地实践

场地预约小程序毕设实战：SSM+微信小程序+MySQL数据库设计到避坑

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？