二级域名分发系统：泛解析、Nginx反代与自动SSL证书

简介在网站托管与多站点管理场景中手动配置DNS解析、Nginx虚拟主机和SSL证书是典型的重复性运维工作耗时长且易出错。二级域名分发系统正是为了将这套流程自动化而生的基础设施工具其核心原理基于DNS泛解析与Nginx反向代理的动态配置生成用户自助申请子域名系统自动校验前缀、生成转发规则并结合ACME协议自动申请SSL证书实现从申请到访问的全链路闭环。这种设计不仅显著降低了运维成本还消除了人工操作引入的配置冲突和安全隐患。对于个人站长、工作室乃至提供公共二级域名服务的平台该系统都能将原先“发域名、配反代、挂证书”的手工流水线转化为高可用的自助服务。本文即围绕这套开源源码从架构设计、核心模块、部署实操到常见排坑完整拆解其落地过程帮助技术团队快速构建自己的域名分发能力。 做过网站托管或者经常给朋友搭站的人应该都有过这种经历新用户来了想开一个独立站点你得先给他开空间、配数据库然后登录域名服务商后台手动加一条A记录再跑到服务器上写一份Nginx配置。运气好一条龙半小时完事运气不好赶上DNS解析延迟用户盯着你催你只能干瞪眼。一两个站还好要是你手里管着几十个域名、上百个站点这套流程能把人活活累到怀疑人生。所以当我看到这套号称“终极最强版”的二级域名分发系统源码时第一反应是这不就是我一直等的东西吗这套系统的核心功能一句话就能说清楚把“手动开站、手动配域名、手动配反代”这一整套流程变成用户在前台自助申请、系统在后台自动分配二级域名、自动生成Nginx反向代理配置、自动申请SSL证书的全自动化流水线。简单说它就是一台“域名发牌机”用户点一下申请域名、解析、转发、HTTPS全部自动搞定。适合谁用个人站长、工作室、企业在内部分发子域名或者你想跑一个类似“免费二级域名”的公众服务都可以拿这套源码直接改。这篇文章我准备从系统设计思路、核心功能拆解、部署实操、问题排查几个维度把我拿到这套源码之后的研究过程和踩坑记录完整写一遍。已经跑通的朋友可以直接跳到后面看排坑部分准备入手的建议从头到尾读完能少走不少弯路。1. 系统设计思路与核心价值1.1 传统域名分配方式的三个痛点先说痛点不然后面讲这套系统的设计逻辑你没有参照系。传统方式给一个新站点分配子域名至少要走三步第一步去域名商后台添加解析记录比如把demo.example.com解析到服务器IP这个过程还有TTL生效时间运气差要等几分钟第二步到服务器上创建网站配置目录写Nginx的server块配置root路径、伪静态规则、反代目标第三步如果需要HTTPS还得申请证书、配置证书路径、设置自动续期。三步走完再让用户去上传代码、导入数据库整个过程臃肿且容易出错。更麻烦的是权限问题。如果你面对的不是懂技术的用户而是普通客户或者同事你不可能把域名后台和服务器SSH的账号直接丢给他们。结果就是所有操作都得你一个人代劳一个人成了全流程的“手动挡业务员”时间全耗在重复劳动上。站点少还能忍站点一多错误率也上来了——端口冲突、证书路径写错、server_name 打错都是常态。1.2 这套系统的核心解决逻辑这套二级域名分发系统本质上是把上面三步自动化串联起来。用户在页面提交一个申请请求填写自己想要的子域名前缀和目标地址系统后台先判断前缀是否被占用、是否符合命名规则然后自动创建解析记录如果你的域名商支持API的话同时调用服务器上的脚本动态生成Nginx配置把http://你的前缀.主域名.com反向代理到用户填写的目标地址。如果是HTTPS再自动调用证书签发工具把证书申请好、配置加载好、重启Nginx生效。整个过程用户感知到的就是从填写表单到拿到一个可用链接通常不超过一分钟。而系统这边每一步都有日志记录出问题能回溯到具体环节。这套逻辑的本质是把“给用户发一个域名”这个动作从“运维手工操作”变成了“产品化自助服务”。你不用再把服务器密码交出去也不用再半夜爬起来给用户手配反代。1.3 适合谁用以及不适合谁用从我实际测试和使用的体验来看这系统的适用场景很清晰。第一类是个人站长手头有主域名想把博客、导航站、工具箱、图床、API服务等一堆子服务都挂到主域名下面用分发系统统一管理比一个个手写Nginx配置要清爽很多。第二类是工作室或者小团队给客户开演示环境的时候不想每开一个演示站都要远程登录服务器部署直接用分发系统让客户自助申请一个二级域名指向演示站地址效率翻倍。第三类是想做“公共二级域名服务”的运营者系统本身就带用户注册、登录、申请、审核模块你可以把它改成一个有用户体系的公共服务平台。但也不是所有场景都适合。如果你对某个站点有极高的性能要求追求每请求独立进程、独立缓存、独立IP或者你需要定制复杂的访问控制规则这套自动化方案反而会限制你的灵活性。分发系统适合的是“数量多、单体轻、自动化优先”的场景不适合“重量级、定制化、固核性能”的场景。2. 核心功能模块与关键技术点拆解2.1 用户端注册、登录与自助申请用户端这套源码做得比较完整。首次使用先注册账号系统默认支持邮箱验证管理员可以在后台决定是“注册即用”还是“注册后人工审核”。登录之后用户会看到一个申请表单需要填写三样东西想要的子域名前缀、目标地址可以是IP端口、域名、或者服务器上的一个路径、备注说明。系统会在前端做一轮基础校验比如前缀是否包含非法字符、是否已经被占用、目标地址格式是否合法这些校验规则都写在源码的公共函数里二次开发很方便。提交之后用户可以在“我的域名”列表里看到自己申请的子域名状态。状态流转大概是待审核 → 审核通过自动开始部署→ 部署成功展示访问链接→ 已停用。每一个状态都有时间戳记录方便后续排查。这里有个细节值得夸一下系统在展示访问链接时会自动拼接https://协议头如果证书尚未生成完成会提示“HTTPS证书部署中请稍后访问”而不是给一个死链这个小设计对用户体验的感知影响很大。2.2 管理端审核、域名池与套餐配置管理后台的逻辑更像个精简版的控制面板。域名管理页面可以看到所有已生成的二级域名列表支持按用户、按前缀、按状态筛选。审核页面处理用户提交的申请可以单个通过也可以批量通过。如果开通了“自动审核”模式那么前置校验通过后系统会自动部署管理员只留查看权限这个模式适合内部可信环境。套餐配置是个亮点功能。管理员可以为不同的用户组设置不同的限额比如普通用户最多申请3个二级域名、VIP用户最多20个每日申请次数也可以单独限制。还有一个“域名池”的概念——你可以预先指定一批后缀词库用户申请时只能从词库中选择避免生成一串无意义的乱码前缀。这个设计对规范命名非常有帮助不然用户随手填一个a1b2c3过两天你自己都记不住这个域名是用来干嘛的。2.3 泛解析与反向代理系统最核心的自动化环节这一节是整个系统的心脏我建议即使不部署这套源码的人也把原理弄明白因为大部分“失效”问题都出在这块。所谓泛解析就是DNS层面设置一个通配符记录*.example.com都解析到你的服务器IP。这样无论用户申请什么前缀只要没被系统显式占用域名的DNS解析已经天然生效了省去了动态调用域名商API的过程。DNS通了之后剩下的问题是Nginx怎么知道某个请求该转发到哪里。这里常规做法是系统在给用户分配域名时在Nginx的conf.d目录下动态生成一个对应的配置文件文件内容的核心就是一段server块server_name 设置为用户的前缀域名location / 里配置 proxy_pass 到用户填写的目标地址。生成完配置之后执行nginx -t校验语法没问题就 reload。我拆了一下源码里的模板生成出来的配置大致长这样根据常见方案整理具体字段各版本略有差异server { listen 80; server_name demo.example.com; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; 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; } }注意proxy_pass这里有两个坑。第一如果用户填的目标地址是http://IP:端口那么proxy_pass后面不能带 URI 路径否则会把路径拼到后端地址后面导致404第二如果目标是HTTPS站点需要在配置里额外加上proxy_ssl_server_name on不然上游SSL握手会报证书不匹配。这套代码默认只是基础反代实际使用中你可能需要针对不同场景调整生成模板。2.4 自动HTTPS证书让分发出去的域名也能上小绿锁既然域名已经出去了没有HTTPS在2025年根本没眼看。浏览器一把大红叉用户直接跑了。这套系统内置了自动证书逻辑靠的是acme.sh或者certbot这类ACME客户端。具体流程是收到部署请求后系统先判断该域名是否已在证书目录中如果不存在就调用证书申请命令成功之后把证书路径写入Nginx配置模板然后reload。这里有一个很重要的问题泛解析出来的子域名申请证书推荐用 DNS API 方式验证域名所有权而不是 HTTP 方式。因为 HTTP 验证要求每个子域名都能在/.well-known/路径下暴露验证文件这对反代到外部服务的场景根本不适用。DNS API 方式则只需要你在证书客户端里配置好主域名的DNS服务商API密钥它就能自动创建一条_acme-challengeTXT 记录完成验证。测试下来只要DNS API配置正确从提交申请到证书签发大概30秒到1分钟就能搞定。2.5 数据统计与流量控制这套源码除了基础的域名创建逻辑还带了一套轻量级的流量统计模块。每个反代请求都会在日志里记录访问时间、来源IP、User-Agent、请求路径后台有汇总页面按小时、天、月维度统计每个子域名的访问量。对于免费分发域名的场景这个功能很有用——你可以看出哪个用户在用、哪个域名成了僵尸站超过30天无访问的可以自动回收。流量控制这块做得比较基础目前是限制单个子域名每分钟的请求数上限超出后返回429。如果你的场景需要更细粒度控制比如按IP限流、按路径限流、按用户套餐限流需要自己改Nginx模板加上limit_req_zone相关配置。不过说实话作为一套开箱即用的源码能做到这一步已经覆盖了80%的需求。3. 部署实操从源码到跑通全流程3.1 环境准备与项目文件结构先把环境要求说清楚。这套源码是基于 PHP 的推荐环境是 Nginx 1.18 / PHP 7.4 / MySQL 5.7服务器系统用 CentOS 7 或 Ubuntu 20.04 都行。如果用过宝塔面板那部署会非常无脑如果喜欢手动配置底下我会给出完整的步骤。拿到源码解压之后目录结构大概是这样的├── app │ ├── controllers # 控制器 │ ├── models # 数据模型 │ └── views # 前端模板 ├── config │ ├── database.php # 数据库配置 │ └── system.php # 系统配置 ├── public │ ├── index.php # 入口文件 │ ├── css │ └── js ├── runtime │ ├── nginx_template # Nginx配置模板 │ └── logs ├── install │ └── index.php # 安装向导 └── upload └── # 上传目录建议先把整个项目传到/www/wwwroot/domain_distributor这类目录并确保runtime目录可写因为系统运行时要动态生成和修改Nginx配置文件。很多人的安装失败都是因为忘了给runtime和upload目录加写权限。3.2 安装配置流程与数据库初始化安装阶段比较简单浏览器访问http://你的服务器IP/install系统会自动跳到安装向导。需要填写的信息有两块数据库连接信息和管理员初始密码。我建议把数据库单独建一个账号别直接用 root安全习惯要养好。安装完成之后记得删除install目录或者重命名它否则会有一个系统级的提醒挂在后台也容易被扫描器盯上。装完之后进入后台第一步去“系统设置”里检查几个关键配置项主域名填example.com泛解析状态确认DNS的*.example.com已经解析到本机证书签发方式选择 DNS API 并填入服务商密钥默认反代目标校验是否允许用户填写内网地址默认建议关闭我实操中遇到过一个问题安装向导默认把“系统URL”填成了http://localhost如果你后续用域名访问后台一定要先把这个改成你的实际访问地址否则后台的静态资源全部会是404。这个坑在源码的官方说明里没有明确写属于经验问题。3.3 域名解析与Nginx宿主配置主域名先要解析好这里有两个记录要加一个是example.com本身A记录指向服务器IP一个是*.example.com泛解析记录也是指向同一个IP。泛解析记录有些DNS服务商是默认关闭的需要先在后台“开启泛解析”选项否则添加记录时会提示格式错误。宿主Nginx配置要注意的是PHP请求要正常转发给php-fpm同时public目录要设成web根目录不然入口文件定位不到。下面是我实际使用的宿主站点配置片段server { listen 80; server_name example.com *.example.com; root /www/wwwroot/domain_distributor/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass unix:/tmp/php-cgi-74.sock; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~ /\.(?!well-known).* { deny all; } }这里必须把example.com和*.example.com都写进server_name否则后续访问任何子域名都会落到默认站点然后被其他配置拦截。我之前就是漏了example.com本身导致域名主站打不开只带了泛解析的子域名能通排查了半天。3.4 后台初始化与生成规则配置管理员后台初始化完成之后建议先到“系统设置”里把三件事做好第一配置发件邮箱因为用户注册、审核通过都会发邮件通知没有SMTP配置用户就收不到状态变更消息第二配置上传参数如果目标是“本目录”。这里的“本目录”是个特殊类型指的是在这个分发系统所在服务器上的某个磁盘路径系统会把用户上传的文件直接解压到该路径并自动创建一个访问子站点。相当于系统也内置了一个“自动建站”功能。第三配置默认审核策略。如果你面向公众建议打开“自动审核”但要配合“目标地址黑名单”一起用防止用户把域名指向一些奇怪的地方。如果面向内部可以直接关闭审核全自动分发。我测试的时候把审核关掉了结果用户申请完立刻生效体验确实很顺滑。但你运营的时候还是要斟酌自动审核意味着你在失去人工把关的能力安全性上要更谨慎。3.5 上线前检查清单部署完之后我习惯按下面这份清单过一遍确认所有环节都正常再正式对外[ ] DNS泛解析生效dig demo.example.com能返回服务器IP[ ] 宿主机80/443端口放行从外网能正常访问主域名[ ] PHP扩展检查curl -m 5 http://127.0.0.1/index.php返回200[ ] runtime目录有写权限后台能正常生成Nginx配置[ ] 证书工具已安装/root/.acme.sh/acme.sh -v有版本输出[ ] SMTP邮箱配置正确注册一个测试用户能收到激活邮件[ ] Nginx reload 没有报错nginx -t返回syntax is ok清单走完整套系统就可以正常对外提供服务了。4. 常见问题与排坑实录4.1 申请后提示“域名解析失败”或“域名状态异常”这个问题我遇到两次第一次是DNS泛解析记录还没生效测试机上本地缓存了旧记录第二次是域名服务商的解析记录里同时存在一条*.example.com和 一条test.example.com二者冲突导致系统查询DNS状态时解析到了不同的IP。排障建议先在服务器执行dig short 你的前缀.主域名.com看结果是不是服务器IP。然后在另一台机器上执行同样的命令如果结果不一致基本就是DNS缓存或记录冲突。泛解析设置后一般几分钟内全球生效但有些本地DNS服务商缓存厉害建议设置TTL为300秒方便后续变更。4.2 反代出现502或504502是这套系统里最高发的问题之一。我的第一反应是看Nginx的error.log里面会明确写着connect() failed (111: Connection refused) while connecting to upstream说明前端Nginx连不上目标地址。这时候要分两种情况排查第一种目标地址本身就是个未启动的端口比如用户填了http://127.0.0.1:8080但8080端口根本没有服务监听那肯定是502第二种目标地址在外网但因为服务器防火墙出口限制连不上对方端口。还有一个容易忽略的点如果用户填的目标地址是https://域名而你的Nginx模板没有配置proxy_ssl_server_name on上游SSL握手会失败同样会报502或504。这套源码默认模板是不带这个参数的我在实际使用中加了这行才解决。4.3 证书签发失败或卡在“证书生成中”证书申请失败的原因90%是DNS验证不通过。用DNS API方式签发时ACME客户端会自动调用DNS服务商的API添加TXT记录但如果你的DNS服务商不在ACME客户端的支持列表里或者API密钥权限不足它就没法自动添加记录然后卡住。另一个常见的坑是主域名已经绑定了太多子域名的证书触发了ACME的“证书数量限制”或“频率限制”。我测试时因为反复申请撤销被Let‘s Encrypt限流了必须等一小时才能继续。解决办法是换用ZeroSSL或者直接等到第二天再试同时检查一下系统的证书管理模块是否实现了“复用已签发证书”的逻辑——如果已经有了同域名的证书不应该重复签发。4.4 后台管理页面登录异常或静态资源丢失登录异常这个问题多半是Session配置问题。PHP的session保存路径如果不可写登录状态就存不下来表现就是刚登录成功又跳回登录页。解决方法是把系统配置中的session路径改到一个可写目录或者直接在php.ini里把session.save_path设为/tmp。静态资源丢失大概率是最开始提到的“系统URL”配置错误。如果你用IP访问过后台系统记录了一个IP地址的URL后续换成域名访问所有基于URL生成的静态资源路径CSS、JS、图片就全部指向IP导致页面裸奔。改回配置并清缓存就好。4.5 高并发下的性能瓶颈与优化这套源码的架构模型里每一次申请动作都会触发Nginx配置生成和reload如果同时有大量申请请求Nginx reload本身的性能损耗就会被放大。实测下来瞬时并发超过30个申请请求时Nginx偶尔会出现worker进程抢占的情况表现为部分请求返回502。优化思路有三个方向第一把Nginx的reload改成nginx -s reload的平滑重载源码里应该已经是这样但要注意别在高频循环里重复调用第二引入消息队列把“申请→配置生成→reload”的流程改成异步任务前端先返回“处理中”后台worker逐个消费任务这样可以打平瞬时尖峰第三Nginx配置层面可以开启open_file_cache减少文件句柄重复开销。流量侧的优化我建议在Nginx模板里直接加上限制limit_req_zone $binary_remote_addr zonedl_limit:10m rate5r/s; server { location / { limit_req zonedl_limit burst10 nodelay; } }这块不是源码默认的能力需要自己改模板加进去。改动前先备份nginx_template目录下的原始模板不然系统升级时会覆盖。5. 扩展玩法与二次开发方向5.1 把分发系统变成APP封装服务现在网上很多人找“通用万能封装APP源码”想把自己的网站、H5游戏、甚至各类在线工具封装成安卓或iOS应用。实际上这套二级域名分发系统完全可以作为“多站点管理的中枢”配合APP封装工具形成一个“用户申请子域名→系统自动开站→一键封装成APP”的服务闭环。具体做法是在用户申请成功页面增加一个“生成APP”按钮APP封装工具通过API接收目标域名地址自动下载网站的前端资源或者直接使用WebView加载域名生成对应的安装包。用户拿到的APP和域名是绑定的后续APP打开的就是自己的专属子站。这个玩法我在测试环境中跑通过配合H5游戏的话完全可以把“游戏盒子”做到自己名下。5.2 对接CDN与智能调度如果你分发出去的域名访问量差异很大有的站一天几百IP有的站一天几万IP可以给系统增加CDN对接能力。系统在生成Nginx配置时同时调用CDN服务商的API把新域名添加为CDN加速域名源站地址设为你的服务器。这样用户拿到的是走CDN的域名源站压力会小很多。注意这里有个关联坑如果加了CDN你的泛解析记录就不能直接指向服务器IP了而是指向CDN服务商提供的CNAME地址。这个改动DNS层和系统层都必须同步调整建议在系统配置里做一个“CDN模式”的开关而不是直接改混淆。5.3 二次开发建议很多朋友拿到源码习惯先改UI。我的建议是UI往后再放先把两个接口改透第一个是远程DNS服务商对接接口如果你的域名商不是源码内置的那几家你需要实现自己的API适配器这个接口在app/services/dns/目录下每个服务商一个类第二个是消息通知接口默认是发邮件你可以改成企业微信机器人、钉钉、或者Server酱方便在多端收到审核提醒。代码层面这个系统的分层算清晰Controller 层很薄核心逻辑都在 Model 和 Service 层改动起来不会牵一发动全身。如果打算商用记得保留日志和备份机制按我的经验这个系统跑在生产环境上最大的风险不是代码bug而是你自己不小心删了runtime目录。写在最后这套源码跑起来之后我一个很直观的感受是以前需要半天才能干完的“发域名、配反代、挂证书”流水线现在变成了用户提交申请后自动完成连提醒邮件都是自动发的。对我这种一个人管几十个站的情况省下的时间不是一星半点。当然“终极最强版”这个说法多少带点标题党的味道但它的功能完整性在同类开源项目里确实算第一梯队如果你正好有分发域名的需求非常值得弄一套试试。最后再分享一个小技巧部署完成后建议定期手动备份runtime/nginx_template和数据库里的域名记录表因为你后面改模板配置时一个不小心生成的Nginx配置可能就带语法错误了。备份一下出问题的时候能快速还原不至于影响线上服务。本文还有配套的精品资源点击获取