基础问题
使用 ZeroNews 需要公网 IP 吗？
不需要。ZeroNews 客户端会主动向服务器发起连接，本地网络无需拥有公网 IP。免费版有什么限制？
免费版提供 1 Mbps 带宽、1 条映射、1 GB 月流量。如需更高资源配额，可升级付费订阅，详见 订阅计划。支持哪些操作系统？
支持 macOS、Windows、Linux（x86_64 / ARM）、Docker，以及 OpenWRT、树莓派和 NAS 系统。隧道与连接
每次启动隧道，域名都会变吗？
不会。每次启动客户端后，已绑定的域名保持不变；只有删除映射并重新通过系统随机域名方式创建隧道时，才会生成新的地址。隧道会自动断开吗？
一般不会。只要客户端持续运行且网络正常，隧道通常会保持连接；如果你主动关闭客户端、关闭终端窗口或设备关机，隧道会中断；如以后台服务方式运行，设备重启后服务会自动恢复。能同时开多条隧道吗？
可以。每条隧道对应不同的本地端口和公网地址，互不干扰；具体可创建数量取决于你的订阅计划。隧道关闭后，我的自定义域名还绑定着吗？
是的。绑定关系会保留，下次启动时使用同一域名即可继续访问。长时间不用的映射会被自动清除吗？
会。端口、映射、认证客户端若连续 90 天未使用，将被自动释放；释放前会通过站内信提前通知，释放后资源不可恢复。详见 数据保留政策。域名与 HTTPS
公网访问地址是 HTTPS 吗？
是的。ZeroNews 默认提供的公网地址均默认启用 HTTPS，证书由 ZeroNews 自动签发和续期。自定义域名的 HTTPS 证书需要我自己申请吗？
不需要。完成 CNAME 验证后，ZeroNews 会自动配置证书；你也可以上传并使用自己的证书。安全性
通过隧道传输的数据安全吗？
是的。本地客户端到边缘服务器之间使用 TLS 加密隧道，公网侧使用 HTTPS。我的 Token 泄露了怎么办？
请立即前往控制台的“关联客户端”页面重新生成 AuthToken；新 Token 生效后，旧 AuthToken 将立即失效，无法继续用于新的认证，但已通过旧 Token 完成认证的设备不会被自动移除。映射访问异常
访问 HTTPS 映射出现 404，怎么办？
这通常说明请求已经到达本地服务，但目标资源不存在。请检查本地服务是否正常运行、请求路径是否正确，以及映射配置中的本地端口是否与服务实际监听端口一致。访问 HTTPS 映射出现 RBAC: access denied，怎么办？
这通常表示该映射启用了客户端认证（RBAC），当前访问请求未提供有效凭据。请前往控制台的“映射管理”中检查认证配置，或使用已授权的客户端进行访问。
访问 HTTPS 映射出现 access denied，怎么办？
这通常表示该映射启用了 IP 黑白名单或地理围栏限制，当前访问 IP 或地区不在允许范围内。请前往控制台的“映射管理 -> 映射详情”中检查访问控制规则。
访问映射时提示 dial local service failed: dial tcp 127.0.0.1:802: connectex: No connection could be made because the target machine actively refused it，怎么办？
这通常表示本地目标服务未启动，或映射配置中的 IP、端口与本地服务实际监听地址不一致。请确认服务已启动，并核对本地 IP 和端口配置是否正确。
我能用 8080 / 80 这种端口吗？
可以。本地端口没有限制，你可以将任意本地端口（如 80、8080、3000 等）暴露到公网；HTTPS 映射的公网访问默认走 443 端口，通常无需在 URL 中额外指定端口号。域名
我可以使用我自己的域名吗？
可以。前提是域名已在第三方服务商注册并完成 ICP 备案，且你的订阅计划包含自有域名功能。如何添加 CNAME 记录？
在控制台完成自有域名审核后，域名详情页会显示主机记录和 CNAME 记录值；前往域名服务商的 DNS 管理后台，新建一条CNAME 记录，按提示填写主机记录和记录值，保存后等待生效即可。
如何申请自有域名 TLS 证书？
完成 CNAME 配置并通过验证后，ZeroNews 会自动为自有域名申请并配置 TLS 证书，无需手动申请；你也可以在控制台上传自己的证书。为什么自有域名 TLS 证书 3 个月要更新一次？
因为 ZeroNews 使用 Let’s Encrypt 等证书服务，证书有效期通常为 90 天。平台会在证书到期前自动续期；如续期失败，请检查 CNAME 记录是否仍然有效。升级
客户端版本支持在线升级吗？
支持。客户端在线时，可通过控制台下发升级指令，客户端会自动完成更新。如何在平台上一键升级？
进入控制台的“客户端”页面，找到目标设备并点击“更新”图标；如有新版本可用，平台会下发升级任务，升级完成通常需要 1 至 3 分钟，可通过zeronews --version 确认版本号。
容器部署的客户端怎么升级？
停止并删除当前容器后，重新拉取最新镜像并按原有挂载方式重新启动即可；升级时请保留原有挂载目录，避免配置丢失。客户端运行
怎么启动客户端？
完成authtoken 认证后，执行 zeronews start 即可启动客户端并激活已配置的映射；macOS 如使用应用目录安装，可在程序目录下执行 ./zeronews start。
客户端支持后台运行吗？
支持。可通过service 命令将客户端注册为系统服务，实现开机自启和后台持续运行；例如 macOS / Linux 可执行 sudo ./zeronews service install 和 sudo ./zeronews service start，Windows 可执行 zeronews service install 和 zeronews service start。
以 Docker 方式运行客户端，为什么要挂载本地目录？
因为客户端的认证配置config.yml 会写入容器中的数据目录；如果不挂载宿主机目录，容器重启或删除后配置会丢失，客户端会变成一台新的未认证设备。
以 Docker 方式运行客户端，为什么每次重启容器都是新客户端？
这是因为没有挂载持久化目录，导致容器重启后config.yml 丢失，客户端重新认证后会生成新的 Client ID，并在控制台中显示为全新设备。
如何停止后台运行的客户端？
如果客户端以系统服务方式运行，可执行zeronews service stop；在 macOS / Linux 上通常需要使用 sudo。
如何卸载客户端的服务？
执行zeronews service uninstall 即可卸载系统服务；在 macOS / Linux 上通常需要使用 sudo。卸载服务只会取消开机自启和后台托管，不会删除客户端程序本身。
客户端常见异常
Windows 客户端安装服务提示 Access is denied，怎么办？
这表示当前终端没有管理员权限。请右键命令提示符或 PowerShell，选择“以管理员身份运行”，再执行 zeronews service install。
客户端提示 connect to cloud server failed (attempt 1): dial tcp: lookup xxxx.zeronews.cc: no such host，怎么办？
这表示 DNS 解析失败。请检查设备网络连接是否正常，以及 DNS 配置是否可用；如有需要，可尝试切换到 8.8.8.8 或 114.114.114.114 等公共 DNS。
客户端提示 connect to cloud server failed (attempt 1): there is another client is running with this clientid: xxxxx，怎么办？
这表示同一个 Client ID 已有另一个客户端实例正在运行。请检查是否在其他进程或设备上重复启动了相同客户端，停止多余实例后再重新启动。
authtoken 认证提示 Local config file already exists, token update ignored，怎么办？
这表示本地已存在配置文件，重复认证时不会覆盖。请先执行 zeronews reset 清理本地配置，再重新执行 zeronews authtoken <your-token>。
authtoken 提示 Authentication failed: invalid authtoken，怎么办？
这表示当前 AuthToken 无效，可能已过期、填写错误或被撤销。请前往控制台重新生成 AuthToken 后再次认证。
authtoken 提示 auth client failed: client count limit reached for this plan，怎么办？
这表示当前订阅计划允许的客户端数量已达到上限。请删除不再使用的客户端，或升级订阅计划以提高限额。
出现 dial tcp: lookup userbackend.v2.zeronews.cc on [::1]:53: read udp [::1]:60123->[::1]:53: read: connection refused，怎么办？
这通常表示本地 DNS 服务无响应或系统 DNS 配置异常。请检查网络状态，必要时重启网络服务，或将 DNS 服务器修改为公共 DNS 后重试。
启动客户端提示 Error: listen tcp 127.0.0.1:37271: bind: address already in use，怎么办？
这表示本地 37271 端口已被占用，通常是另一个客户端实例已在运行。请先停止已有客户端进程，再重新启动；必要时可检查占用该端口的其他程序。
Linux 客户端执行 start 时提示 create temp runtime file: open /etc/zeronews/prg_runtime-xxxxxxxxxx.tmp: permission denied，怎么办？
这表示运行时目录权限不足。请使用 sudo 执行启动命令，例如 sudo ./zeronews start，或确保服务安装时使用了管理员权限。
Linux 客户端安装服务提示 installing service requires administrator privileges. Please run with sudo，怎么办？
这表示安装系统服务需要管理员权限。请使用 sudo 重新执行安装命令，例如 sudo ./zeronews service install。
客户端提示 Connection failed: dial tcp x.x.x.x:7000: i/o timeout，怎么办？
这表示客户端无法连接服务器的 7000 端口，通常是防火墙或网络策略拦截了出站连接。请检查本地防火墙、代理和上游网络策略，确认允许向目标服务器发起 TCP 出站连接。
Linux 以服务方式启动客户端时提示 Failed to start zeronews-client.service: Unit zeronews-client.service not found，怎么办？
这表示服务尚未安装。请先执行 sudo ./zeronews service install，再执行 sudo ./zeronews service start。
故障迁移与恢复
迁移与恢复在什么时候会用到？
当你需要更换设备、重装系统、迁移服务器，或在新机器上继续使用原有客户端身份和映射配置时，可通过恢复客户端配置来避免重新认证和重建映射。如何在 Windows 上恢复现有客户端映射配置？
可在新设备上重新安装客户端，然后使用恢复命令执行zeronews authtoken <token> <客户端ID>；恢复成功后再执行 zeronews start，原客户端映射配置会自动下发到新设备。
如何在 Linux 上恢复现有客户端映射配置？
可在新设备上安装客户端后执行zeronews authtoken <token> <客户端ID>，恢复完成后再执行 zeronews start，原客户端映射配置会自动同步。
如何在 macOS 上恢复现有客户端映射配置？
可在终端进入客户端目录后执行./zeronews authtoken <token> <客户端ID>，恢复完成后再执行 ./zeronews start，原客户端映射配置会自动同步。
如何在 Docker 上恢复现有客户端映射配置？
如果原容器已挂载宿主机目录，重新运行容器时继续挂载同一目录即可自动恢复；如果之前未挂载目录，原配置已丢失，只能重新执行authtoken 认证。
其他
怎么重置客户端？
执行zeronews reset 即可清除本地配置文件和日志；重置完成后，需要重新执行 authtoken 认证才能使用客户端。macOS / Linux 通常需要使用 sudo 命令。
怎么查看客户端日志文件？
客户端日志文件通常位于安装目录下的logs/ 文件夹中，例如 macOS 可位于 /Applications/zeronews/logs/；你也可以在控制台的“可观测性 -> 映射访问日志”中查看映射维度的请求日志。