KPanel 进阶玩法：自定义 DDNS 域名访问，同时保留内网 IP 入口

已经在家里的小主机、NAS 或动态 IP 服务器上用起 KPanel，想把日常访问入口换成自己的 DDNS 域名，同时保留内网 IP 直连？这篇补充教程就是给有动手能力的用户准备的。

单个 DDNS 域名可以通过现有配置实现，不需要修改 KPanel 代码，也不需要关闭 Host 校验。做法是把 DDNS 域名设置为主要访问地址，再保留 IP 访问选项。

基础功能可参考：KPanel 集群监控实战教程。本文集中讲自定义访问入口。

一、我们要实现什么效果？

以 HTTP 直连场景为例，配置完成后可以使用以下两个入口：

• 在家中通过内网地址访问，例如 http://192.168.1.100:9102。
• 通过自己的 DDNS 域名访问，例如 http://panel.example.com:9102。

这里的域名、IP 和端口都是示例，需要换成自己的实际配置。DDNS 负责跟踪地址变化；KPanel 负责识别你配置的访问来源。IP 变化后，只要域名和访问端口不变，通常无需反复修改面板配置。

HTTP 适用于受控网络或经 VPN 保护的链路；需要直接在公网长期访问时，建议配置 HTTPS，文末有对应说明。

二、先满足这些条件

• KPanel 已经运行，并且原来的 IP 入口可以使用。
• DDNS 域名已正确解析到目标地址，端口转发和防火墙放行已经配置好。
• 你能通过 SSH 编辑服务器上的环境配置文件。

公网 IPv4 对应 A 记录；公网 IPv6 对应 AAAA 记录。使用 IPv6 时，访问端也需要 IPv6 连通性，并确认解析的是 KPanel 所在设备的地址。DDNS 不会自动解决 CGNAT、开放端口或生成 HTTPS 证书。动态解析原理可参考 Cloudflare 官方说明。

使用 Cloudflare 的朋友，如果要通过示例中的 9102 端口直连，请使用 DNS only（灰云）。9102 不在 Cloudflare 普通代理支持的端口列表中，详情见官方端口说明。

三、修改 KPanel 的主要访问地址

以下路径适用于 kejilion.sh 应用市场的标准部署。手工部署的用户，应按自己的 Compose 目录调整。

1. 备份并打开配置文件

通过 SSH 登录主机，用具有相应权限的账户执行：

cd /home/docker/kpanel
cp -p -i .env .env.before-ddns
nano .env

先确认切换目录成功再执行后续命令。备份文件已存在时，cp -i 会询问是否覆盖，请保留需要的旧备份。没有 nano 也可以使用 vi。

2. 设置这三个配置项

找到原来的对应配置并修改，不要在文件末尾重复添加同名项目，其余内容保持原样：

KPANEL_PUBLIC_URL=http://panel.example.com:9102
KPANEL_SECURE_COOKIE=false
KPANEL_ALLOW_IP_HOSTS=true

• KPANEL_PUBLIC_URL：主要访问地址，填写浏览器实际使用的协议、域名和端口。
• KPANEL_SECURE_COOKIE：HTTP 示例使用 false；已配置好的 HTTPS 入口使用 true。
• KPANEL_ALLOW_IP_HOSTS：设为 true，继续允许通过内网等 IP 地址访问。

例如，路由器把外网 19102 转发到主机 9102，那么这里应该填写 http://panel.example.com:19102，因为它才是浏览器实际使用的入口。修改这个变量本身不会改变 Docker 端口映射或路由器转发。

地址中不要添加登录路径、查询参数，也不要用逗号拼接多个域名。这里配置的是一个主要访问来源，不是任意域名白名单。

3. 重新创建面板容器，使配置生效

保存文件后，仍在同一个目录中执行：

docker compose --env-file .env config --quiet

确认没有配置错误，再执行：

docker compose --env-file .env up -d --no-deps --force-recreate --pull never panel
docker compose --env-file .env ps

这会短暂重建 panel 服务，当前面板连接和终端会话会中断，请先结束正在进行的面板操作。命令禁止拉取新镜像，不要求重建其他业务容器，也不需要删除 KPanel 数据。

这里需要重建容器，而不是只执行 restart：环境变量变化不会通过简单重启注入已有容器。参见 Docker 的 restart 说明与 up 说明。

四、分别验证 DDNS 和内网 IP

1. 打开配置中的完整 DDNS 地址，确认能进入面板并正常登录。
2. 在局域网中使用原来的内网 IP 和端口，确认仍然可用。
3. 需要远程访问时，再切换到真正的外部网络测试；仅在家里测试不能代表外网已打通。

如果 DDNS 入口返回 421 Host validation failed，说明请求已经到达 KPanel，可以优先核对主要访问地址，以及新环境配置是否已通过重建容器生效。若只是连接超时，则先查 DNS、地址可达性、端口转发和防火墙。

KPANEL_ALLOW_IP_HOSTS=true 允许的是 IP 地址访问，不代表自动允许所有域名。显式设置自己的 DDNS 域名，可以继续保留 Host 与同源校验。

五、使用 HTTPS 反向代理时怎么配？

如果已经有配置好证书的 HTTPS 反向代理，主要访问地址可以写为：

KPANEL_PUBLIC_URL=https://panel.example.com
KPANEL_SECURE_COOKIE=true
KPANEL_ALLOW_IP_HOSTS=true

使用非默认 HTTPS 端口时，记得写上端口，例如 https://panel.example.com:8443。反向代理需要正确传递 Host 和访问协议，代理来源也需要在 KPanel 的可信代理范围内；不要把所有来源都设为可信代理。

把配置里的 http 改成 https，不会自动签发证书或启用加密。应先准备好实际可用的 HTTPS 入口。标准反代配置可参考 KPanel 部署文档。

另外，启用 Secure Cookie 后，普通 HTTP 内网 IP 入口可能仍能打开页面，但浏览器不会通过 HTTP 发送安全会话 Cookie，不能保证沿用原来的 HTTP 登录体验。需要同时保留内外网管理时，可以让内网 DNS 将同一个 HTTPS 域名解析到内网入口，并确保内部反代端口和证书匹配。

六、需要恢复原配置时

确认备份是本次修改前的文件，再在 KPanel 目录恢复：

cd /home/docker/kpanel
cp -p .env.before-ddns .env
docker compose --env-file .env config --quiet

检查通过后重新创建面板容器：

docker compose --env-file .env up -d --no-deps --force-recreate --pull never panel

恢复环境配置不会撤销你另行修改的 DNS、路由器转发或反向代理，需要时分别恢复即可。操作期间保留 SSH 连接，方便调整访问入口。

对于单个 DDNS 域名，这套现有配置就能实现自定义访问。HTTP 直连方案还可保留内网 IP 登录；长期公网使用则结合 HTTPS 和适当的入口限制。整个过程无需改代码，也无需放开任意域名。

延伸阅读：KPanel 集群监控实战 · KPanel 项目