常见问题
部署
一定要副节点吗?
不需要。一个主节点就能完整工作。副节点只是用来在多地分摊下载带宽的优化项,小规模/单地区完全不用上。
一定要 PostgreSQL 吗?
不。SQLite / MySQL / PostgreSQL 三选一,SQLite 最省事(单文件零运维),适合起步。需要更强并发或横向扩展时再迁到 PostgreSQL。见 选择数据库。
要手动建表吗?
不用。主节点启动时自动执行内嵌迁移(CREATE TABLE IF NOT EXISTS,幂等)。除非你用 CNV_SKIP_MIGRATE=1 关掉它并自己管 schema。
第一个管理员怎么来?
服务端不会自动建。用 admintool create-admin 引导(见 快速部署)。
需要前端构建吗?(npm run build?)
不需要。管理后台前端是 React + 浏览器内 Babel,服务端直接静态分发 .jsx,没有构建步骤。注意:这里说的是业务前端;你现在读的这套文档站是 VitePress,那个才需要 npm 构建。
客户端连不上 / 行为异常
所有客户端都被要求强制更新?
allowed_versions 白名单里没有当前客户端版本。去后台「版本管理」把当前发布版本加进白名单。空白名单 = 拒绝所有客户端。
客户端握手被拒(signature_rejected)?
签名校验没过。要么:
- 你配的
CNV_SIGNATURE_WHITELIST与客户端实际签名证书摘要不一致 —— 重新用keytool -exportcert ... | sha256核对; - 或客户端确实是改包的(正常风控,应当拒绝)。
调试时可临时清空白名单(放行所有,仅开发)。见 防改包闸门。
卡在"维护中"?
后台「服务器控制」状态是 维护中。切回 正常。
边缘节点不出现 / 面板连不上节点?
- 节点首次启动会在日志打印连接密钥;确认已把它和
ctrl_url(ws://host:9090/ctrl)、api_url一起填进面板节点注册表。 - 跨机部署时节点须设
CNV_CONTROL_ADDR=:9090(默认只绑127.0.0.1),并在防火墙对面板放行该端口。 - 面板「节点状态」页确认节点
online=true;离线时面板每 30s 自动重连。 - 客户端要看到边缘节点,需业务节点配置了
CNV_DIRECTORY_FILE(已签名目录,且该节点声明了caps: ["resource"])。
来源 IP / 限流
限流好像把所有人当成一个人?
放在反代后面却没设 CNV_TRUST_PROXY,导致所有请求 IP 都记成网关 IP,IP 维度限流退化成全局共享一个桶。设对 CNV_TRUST_PROXY 并让网关重写转发头。见 受信任代理。
审计日志里 IP 全是内网网关地址?
同上,trust proxy 没配对。
账号 / 邮件
注册收不到验证码?
当前实现把验证码写入数据库,实际发信需要你对接外部邮件服务(本仓库不含 SMTP 客户端)。本地开发可设 CNV_EMAIL_DEV_MODE=on 把验证码打到日志看。
生产别开 EMAIL_DEV_MODE
开着等于把验证码公开在日志里。生产必须关闭(默认即关)。
玩家忘了密码?
让玩家走「找回密码」(邮箱验证码),或管理员用 admintool reset-account 重置。
玩家想多设备登录?
支持。玩家会话按 token 管理,可在「用户中心」看到所有登录设备并踢下线。改密码会让其它设备下线。
数据 / 备份
最该备份什么?
数据库里的 config(配置)、accounts(玩家)、saves(存档)。整库定期快照即可。见 日常运维。
云存档有多大限制?
全站请求体上限 8 MiB;云存档上传额外限速单会话 2 次/分钟,防刷。
能从 SQLite 迁到 PostgreSQL 吗?
可以,schema 简单。用新 DSN 启动建表,再用通用工具搬数据。见 选择数据库。
升级 / 运维
升级会丢数据吗?
不会。迁移只新增表/索引(IF NOT EXISTS),不动既有数据。但升级前务必先备份数据库。
改了后台配置要重启吗?
不用。配置写数据库,客户端下次握手即生效。改 CNV_* 环境变量才需要重启。
怎么平滑停机?
systemctl stop 或 Ctrl-C 发 SIGTERM,进程会给在途请求最多 10 秒优雅收尾再退出。