常见问题

首次启动后管理员密码在哪里？

首次启动时，如果未在 config.yaml 中设置 admin.initial_password，系统会自动生成一个 32 位随机密码并输出到终端。如果使用 Supervisor 或 systemd，可以在日志中查找：

# Supervisor（密码输出到 stderr，Supervisor 默认会将其重定向到日志）
grep "密码" /var/log/novaix/app.log

# systemd
journalctl -u novaix | grep "密码"

WARNING

自动生成的密码只会在首次启动时输出一次。如果您没有及时记录，将无法再次查看。建议在部署时通过 config.yaml 的 admin.initial_password 指定初始密码（仅首次启动生效）。

忘记了管理员密码怎么办？

有以下几种方式重置管理员密码：

1. CLI 命令行（推荐）：使用 novaix admin:reset-password 命令直接重置，支持 -u 指定用户名（默认 admin）、-p 指定新密码（不指定则自动生成）。详见 CLI 管理工具
2. 忘记密码功能：如果配置了邮件服务或短信服务，可以通过登录页面的「忘记密码」功能，使用邮箱验证码或手机短信验证码重置密码

环境变量和配置文件的关系？

所有配置项都可以通过 NOVAIX_ 前缀的环境变量覆盖。环境变量的优先级高于配置文件。

命名规则：去掉 NOVAIX_ 前缀后，第一个 _ 分割为配置段和键名，后续下划线保留。例如 server.port → NOVAIX_SERVER_PORT，database.max_open_conns → NOVAIX_DATABASE_MAX_OPEN_CONNS。

可以同时使用多种数据库吗？

不可以，同一时间只能使用一种数据库（SQLite、MySQL 或 PostgreSQL）。如果需要从 SQLite 切换到 MySQL 或 PostgreSQL，需要手动迁移数据。

节点连接失败怎么排查？

1. 确认节点已完成初始化（未初始化的节点无法连接管理 API）
2. 确认管理端口（默认 8443）已开放，没有被防火墙或安全组拦截
3. 确认节点服务器的管理服务正在运行
4. 在节点列表中使用「测试连接」功能查看具体的错误信息
5. 如果使用了自签名证书，确认 config.yaml 中 node.insecure_skip_verify 为 true（默认值）

TIP

Novaix 与节点之间通过 HTTPS（默认 8443 端口）通信。请确保 Novaix 服务器能访问节点的该端口，中间没有 NAT、安全组或防火墙拦截。

WebSocket 连接失败（终端/控制台无法打开）？

通常是反向代理配置问题。请确保您的 Nginx 或 Caddy 配置正确转发了 WebSocket 连接。参考安装章节中的 Nginx 配置示例，确保包含了 Upgrade 和 Connection 头的转发。

终端和控制台使用 WebSocket 实时通信。认证流程是先通过 POST /api/v1/auth/ws-ticket 获取一次性 ticket（30 秒有效），然后拼接到 WebSocket URL 的 token 参数中。如果 ticket 过期或反向代理未正确转发 WebSocket 请求，连接将失败。

支付回调没有生效？

1. 确认回调地址（如 https://您的域名/api/callbacks/alipay）可以从公网访问
2. 确认使用的是 HTTPS
3. 检查支付渠道的密钥配置是否正确
4. 查看 Novaix 日志中是否有相关错误信息
5. 确认反向代理没有修改或丢弃请求体（部分 WAF 可能拦截回调请求）

镜像上传中断了怎么办？

镜像上传基于 TUS 协议实现了断点续传，刷新页面后重新选择同一文件上传即可自动从中断处继续，无需重新开始。

如何修改监听端口？

修改 config.yaml 中的 server.port，或通过环境变量 NOVAIX_SERVER_PORT 设置。修改后需要重启服务。同时记得同步修改反向代理中的 proxy_pass 地址。

TOTP 双因素认证丢失了怎么办？

如果您丢失了 TOTP 设备（手机损坏、应用被删除等），目前没有自助恢复方式，需要运维人员在数据库中手动清除用户的 TOTP 绑定状态。请在绑定 TOTP 时务必将密钥或 otpauth URI 备份在安全的地方，以便在更换设备时重新导入。

用户购买后实例一直显示「创建中」？

1. 检查「任务管理」中对应的创建任务状态和日志
2. 如果任务失败，查看日志中的错误信息。常见原因包括：
   • 节点连接中断或服务端口不可达
   • 镜像未分发到目标节点
   • 节点磁盘空间不足
   • IP 池没有空闲 IP
3. 如果任务长时间处于「运行中」无进展，可能是节点负载过高或网络中断

实例到期后会被直接删除吗？

实例到期后系统会按「暂停宽限天数」配置自动冻结实例（默认 0 天，即到期立即冻结），不会立即删除。到期后超过「删除宽限天数」（默认 7 天，从到期时间起算）且仍处于冻结状态时才会自动删除。冻结期间续费后实例恢复为已停止状态，需手动启动。建议设置合理的宽限期，给用户足够的时间续费。

更换了服务器怎么迁移？

1. 在旧服务器上停止 Novaix 服务
2. 将整个工作目录（默认 /opt/novaix）复制到新服务器
3. 将二进制文件 /usr/local/bin/novaix 复制到新服务器
4. 在新服务器上启动服务
5. 更新反向代理配置和 DNS 解析

如果使用 SQLite，数据库文件在工作目录下，一起复制即可。如果使用 MySQL 或 PostgreSQL，还需要单独迁移数据库。

WARNING

迁移后请确保 config.yaml 中的 server.external_url 和 server.allowed_origins 与新的域名一致。如果域名不变则无需修改。

debug 模式和 release 模式有什么区别？

特性	debug	release
错误详情	在 API 响应中返回详细错误堆栈	只返回通用错误信息
日志级别	输出更详细的调试日志	仅输出 info 及以上级别
演示模式	可启用	不可启用

API 文档（/docs）的访问由后台「高级设置」中的「API 文档」开关控制，默认关闭，与运行模式无关。

生产环境必须使用 release 模式。debug 模式仅用于开发和测试，在生产环境中使用会暴露敏感的错误信息，存在安全风险。

VPC 创建失败提示 OVN 未启用？

VPC 依赖 OVN 网络。请确认：

1. 节点组创建时已勾选「启用 OVN」
2. OVN 上行网络接口名称填写正确（如 eth0）
3. 节点服务器上已安装并配置好 OVN 组件
4. 节点组内至少有一个在线节点

按小时计费的实例停止后还会扣费吗？

不会。按小时计费只在实例处于「运行中」状态时产生费用。停止、冻结状态的实例不会被扣费。实例恢复运行后继续扣费。

如果控制面停机期间实例仍在运行，恢复后系统会自动补扣停机期间的费用（最多补扣 30 天）。余额不足时，会扣除可支付的小时数后冻结实例。

rDNS 记录一直显示同步失败？

1. 确认 PowerDNS API 地址和密钥配置正确
2. 确认 Novaix 服务器能访问 PowerDNS API 端口
3. 确认 PowerDNS 中已创建对应的反向解析区域
4. 查看记录列表中的具体错误信息

数据库文件越来越大怎么办？

如果使用 SQLite，数据库文件会随着监控数据、操作日志等的累积而增大。您可以：

1. 调低 collector.retention（监控数据保留时间，默认 720 小时即 30 天），减少历史监控数据
2. 定期在管理面板中清理过期的任务日志
3. 使用 SQLite 的 VACUUM 命令回收空间：

   # 停止 Novaix 后执行
   sqlite3 /opt/novaix/novaix.db "VACUUM;"

如何启用高可用（HA）多实例部署？

从 v0.2.3 起，Novaix 支持多实例部署。需要满足以下条件：

1. 使用 MySQL 或 PostgreSQL 数据库（SQLite 不支持 HA）
2. 在 config.yaml 中设置 ha.enabled: true
3. 所有实例使用相同的数据库、jwt.secret、security.encryption_key
4. 共享 storage.image_dir（通过 NFS 或对象存储挂载）
5. 前端使用负载均衡器（如 Nginx upstream）分发请求

启用后，计费、指标采集、任务运行等后台任务会通过分布式锁保证同一时刻只在一个实例上执行。

从 SQLite 迁移到 MySQL / PostgreSQL 的步骤？

1. 停止 Novaix 服务
2. 创建目标数据库（MySQL 推荐 utf8mb4 字符集）
3. 修改 config.yaml 中 database.driver 为 mysql 或 postgres，填写对应的 DSN（格式参考配置参考）
4. 启动 Novaix，系统会自动在目标数据库中执行迁移创建表结构
5. 使用第三方工具将 SQLite 数据导入目标数据库

WARNING

迁移前务必备份 SQLite 数据库文件。迁移后请验证数据完整性。

插件安装后没有生效？

1. 确认插件已在「插件管理」中启用（开关为开启状态）
2. 确认插件配置已正确填写（如 API 密钥、回调地址等）
3. 查看「关于」页面确认 Novaix 版本是否满足插件的最低版本要求
4. 查看终端/日志中是否有插件加载错误信息
5. 尝试禁用后重新启用插件

代理（Agent）系统如何运作？

代理系统允许您发展分销商，代理商可以推广您的服务并获得返佣：

• 首单佣金：用户通过代理链接注册后首次付款，代理获得一次性佣金
• 续费佣金：该用户后续每次续费，代理持续获得佣金
• 佣金比例通过「代理组」配置，不同组可设置不同费率
• 代理可在用户面板的「代理中心」查看推广链接、下线用户和佣金明细

如何配置自定义域名访问？

1. 将域名 DNS 解析到服务器 IP
2. 配置 Nginx/Caddy 反向代理（参考安装章节）
3. 申请并配置 SSL 证书（推荐使用 Let's Encrypt）
4. 修改 config.yaml 中 server.external_url 为您的域名
5. 修改 server.allowed_origins 为您的域名
6. 重启 Novaix

支持哪些操作系统镜像？

Novaix 支持主流 Linux 发行版镜像，包括但不限于：

• Ubuntu、Debian、CentOS、Rocky Linux、AlmaLinux
• Alpine、Arch Linux、Fedora、openSUSE
• Windows（需要 QEMU 虚拟机类型）

镜像可以从远程镜像源（如 images.linuxcontainers.org）拉取，也可以通过 URL 下载或手动上传。

如何限制用户可购买的实例数量？

目前可以通过以下方式间接控制：

1. 限制 IP 池中的可用 IP 数量
2. 限制节点组的资源配额
3. 通过套餐的库存设置控制可售数量

实例快照占用多少存储空间？

快照使用写时复制（CoW）机制，仅记录自快照创建以来变化的数据块，初始几乎不占用额外空间。随着实例数据变化，快照占用空间会逐渐增大。建议定期清理不再需要的历史快照。

自动续费是怎么工作的？

自动续费通过每小时执行的定时任务检查。在实例到期前 24 小时，系统自动尝试从用户余额中扣除续费金额：

• 余额充足：自动创建已支付的续费订单，延长到期时间，用户会收到续费成功通知
• 余额不足：跳过续费，发送续费失败通知，实例到期后按正常流程冻结
• 如果实例因欠费已被冻结，自动续费成功后会恢复为「已停止」状态，需手动启动

续费金额取决于「系统设置 → 实例生命周期 → 续费价格策略」：默认跟随套餐当前价格，如果管理员改过价则按新价续费；设为「锁定购买时价格」后，续费按实例开通时的价格计算，改价不影响已有实例。

用户可以在实例详情页随时开启或关闭自动续费，独立于到期冻结/删除流程。

系统有哪些自动执行的定时任务？

Novaix 内置多个定时任务，每小时执行一轮：

任务	说明
按时计费	对运行中的按小时实例扣费
自动续费	到期前 24 小时自动扣余额续费
冻结到期实例	超过暂停宽限期后冻结实例
删除超期实例	超过删除宽限期后删除冻结实例
取消超时订单	取消超过 24 小时未支付的订单
月度流量重置	每月 1 号清零流量使用量
流量同步	从监控数据聚合计算实例流量使用量
流量超额检查	根据策略执行限速/按量计费/暂停
流量告警	流量使用达 80% 时发送告警通知
到期提醒	到期前 3 天发送提醒通知
自动备份	按策略创建快照并清理超出保留数量的旧备份

HA 模式下，同一时刻只有一个实例执行定时任务（通过分布式锁保证）。

流量超额后会怎样？

流量超额处理取决于后台「生命周期设置」中的「流量超额策略」：

策略	说明
限速	将实例带宽限制到较低速率，不额外收费
按量计费	按超额流量每 GB 收费，从用户余额扣除；余额不足时自动降级为限速
暂停	直接冻结实例，直到下月流量重置或用户购买流量包
忽略	不做任何处理

流量使用达到 80% 时，系统会自动发送告警通知。每月 1 号流量使用量自动清零并解除限速。用户也可以随时购买流量包增加额度。

实例重装系统后哪些数据会保留？

重装系统会完全清除实例内的所有数据（系统盘和数据盘），使用新镜像重新创建实例。以下信息会保留：

• IP 地址和网络配置
• 端口转发规则
• 防火墙规则
• VPC 挂载关系
• 到期时间和计费信息

重装前建议创建快照或备份重要数据。重装需要实例处于停止状态。

实例密码重置后为什么没有立即生效？

密码重置通过修改 cloud-init 配置实现，新密码需要重启实例后才能生效。重置操作会更新实例的 cloud-init 用户数据，在下次启动时应用新密码。如果您需要立即使用新密码，请在重置后手动重启实例。

Webhook 回调的重试机制是什么？

Webhook 回调最多尝试 3 次（1 次初始投递 + 2 次重试），重试间隔分别为 5 秒、10 秒和 15 秒。回调请求超时时间为 10 秒。如果回调端返回的 HTTP 状态码 ≥ 300 或请求超时，视为失败并触发重试。

回调请求头包含 X-Novaix-Signature（HMAC-SHA256 签名），接收方应验证签名以确保请求来源可信。全局最大并发投递数为 32，超出时本次回调会被丢弃。

优惠券有哪些使用限制？

优惠券支持以下限制条件：

• 最低消费：订单金额需达到优惠券设置的最低使用金额
• 使用次数：可设置总使用次数上限和每用户使用次数上限（默认每人 1 次）
• 有效期：可设置开始时间和结束时间
• 适用类型：可限定仅适用于特定订单类型（新购、续费、升级等）
• 折扣上限：百分比优惠券可设置最大折扣金额

优惠券不能叠加使用，每个订单最多使用一张。

encryption_key 和 jwt.secret 有什么区别？

这是两个独立的安全配置，用途不同：

• jwt.secret：用于签发和验证 JWT Token，决定用户登录状态的安全性。修改后所有已登录用户的 Token 会失效，需要重新登录
• security.encryption_key：用于 AES-256-GCM 加密敏感数据（如实例密码、节点 SSH 密钥等）。修改后已加密的数据将无法解密，导致节点连接失败等问题

DANGER

encryption_key 一旦设置并有数据写入后不可更改。请妥善保管，丢失后无法恢复已加密的敏感数据。生产环境务必设置一个强随机字符串。

Novaix 自身需要配置 SSL 证书吗？

不需要。Novaix 本身只监听 HTTP，SSL/TLS 由前端的反向代理（Nginx 或 Caddy）处理。推荐使用 Caddy（自动申请和续期 Let's Encrypt 证书，零配置）或 Nginx + certbot。

Novaix 服务本身的配置只需关注 server.external_url 设置为 https:// 开头的完整域名即可。

有 API 限流吗？

有。Novaix 内置了基于 IP 的请求速率限制：

• 公开接口（登录、注册、验证码等）：每分钟 15 次请求，突发容量 20 次
• 认证接口（登录后的 API）：每秒 10 次请求，突发容量 60 次

超过限制的请求会返回 HTTP 429 错误。如果您使用了反向代理，请确保配置了 server.trusted_proxies，否则所有请求会被识别为同一 IP。

反向代理报 CORS 跨域错误？

检查以下配置：

1. config.yaml 中 server.allowed_origins 必须包含您的域名（如 https://panel.example.com），生产环境不要使用 *
2. 确认反向代理没有额外添加 CORS 头（与 Novaix 自带的冲突会导致浏览器报错）
3. 如果使用 Caddy，默认行为通常不需要额外配置

浏览器控制台报 Content Security Policy 错误？

系统内置了 CSP（内容安全策略）来防御 XSS 攻击，默认只允许加载自身域名的资源。如果您使用了 Cloudflare Web Analytics、第三方客服、统计等服务，这些外部脚本会被浏览器拦截。

解决方法：在后台「系统设置」→「高级设置」→「CSP 额外白名单」中，将第三方服务的域名添加到对应的指令白名单中。例如使用 Cloudflare Web Analytics 时，在 script-src 和 connect-src 中添加 https://static.cloudflareinsights.com。

如果使用了极验验证码插件，系统会自动处理其所需的 CSP 配置，无需手动添加。

反向代理需要怎么配置 trusted_proxies？

当 Novaix 部署在反向代理后面时，需要配置 server.trusted_proxies 以正确获取客户端真实 IP：

server:
  trusted_proxies:
    - "127.0.0.1"       # 本机代理
    - "10.0.0.0/8"      # 内网代理

如果不配置，所有请求的客户端 IP 都会被识别为反向代理的 IP，导致：

• 速率限制对所有用户共用同一个配额
• 登录日志中无法区分不同用户

监控数据采集间隔和保留时间？

默认配置：

• 采集间隔：60 秒（collector.interval）
• 保留时间：720 小时 / 30 天（collector.retention）
• 单次采集超时：10 秒（collector.timeout）

采集的指标包括 CPU 使用率、内存使用量、磁盘使用量和网络流量。用户在实例详情页可以查看 1 小时、6 小时、24 小时、7 天和 30 天的监控图表。

如果监控数据占用存储过大，可以缩短保留时间或增大采集间隔来减少数据量。

自动备份是怎么配置的？

自动备份在后台「系统设置」→「自动备份」中配置，包含以下选项：

• 启用开关：全局开关，默认关闭
• 执行时间：每天的哪个小时执行（如凌晨 3 点）
• 频率：每天（daily）或每周（weekly）
• 保留数量：超出数量的旧备份会被自动清理

自动备份的前提是单个实例也开启了「自动备份」开关。只有处于运行中或已停止状态的实例才会被自动备份。备份本质是创建快照，命名格式为 auto-20260709-030000。

免费版和授权版有什么区别？

免费版可以正常使用核心功能，但以下功能受限：

功能	免费版	授权版
节点数量	最多 2 个	无限制
VPC 私有网络	❌	✅
共享 IP / NAT	❌	✅
高可用（HA）	❌	✅
代理/分销系统	❌	✅
开放接口	❌	✅
品牌自定义	❌	✅
团队成员	❌	✅
告警通知	❌	✅
插件系统	❌	✅

演示模式有什么限制？

演示模式（demo.enabled: true）不能在 release 模式下启用，用于展示系统功能。启用后系统会按 demo.reset_interval（默认 1 小时）定期重置数据。

演示模式下，在线更新等敏感操作会被阻止（除非请求头携带旁路密钥）。设置变更不会实际保存。

WARNING

生产环境必须使用 release 模式，因此演示模式会被自动阻止。如果配置了 demo.enabled: true 但运行在 release 模式下，系统启动时会报错。

用户注册有哪些限制条件？

用户注册功能由后台「系统设置」中的全局开关控制（默认关闭）。支持以下注册方式：

• 邮箱注册：可选择是否要求邮箱验证（默认开启）
• 手机号注册：需先配置短信服务
• OAuth 登录注册：支持 GitHub、Google、微信和通用 OIDC 协议

注册时用户名要求 2-32 个字符，密码要求 6-72 个字符。如果启用了人机验证（通过验证码插件），注册时需通过验证。

工单系统支持邮件回复吗？

支持。配置了邮件服务并设置了入站 Webhook（Mailgun/Resend 的 Inbound 功能）后，用户回复工单通知邮件时，系统会自动将邮件内容创建为工单回复，无需登录面板。

管理员在工单中的回复也会通过邮件通知用户。

用户能管理 SSH Key 吗？

可以。用户可以在个人设置中管理 SSH 公钥：添加、查看（仅显示名称和指纹，不返回完整公钥）和删除。同一用户不允许添加指纹相同的重复密钥。

购买实例时可以选择已有的 SSH Key 注入到新实例中，免去手动配置密码登录的步骤。

支持哪些 OAuth 登录方式？

内置支持以下 OAuth 提供商：

• GitHub
• Google
• 微信
• 通用 OIDC（兼容任何标准 OpenID Connect 提供商）

每个提供商默认关闭，需管理员在后台启用并配置密钥。此外，通过插件系统还可以扩展支持更多 OAuth 提供商。

已登录用户可以在个人设置中关联或解除关联社交账号。

支持实名认证（KYC）吗？

支持，但默认关闭。开启后支持两种认证模式：

• 二要素验证：姓名 + 身份证号（默认）
• 人脸识别：在二要素基础上增加 H5 活体检测

认证渠道支持阿里云和腾讯云。认证通过后用户信息脱敏存储，不可重复认证。详细配置参见实名认证文档。

系统支持哪些通知渠道？

除了邮件和短信外，Novaix 还支持以下管理员告警通知渠道：

• Telegram Bot
• 钉钉机器人
• 企业微信机器人
• 通用 Webhook

这些通知渠道用于向管理员推送系统告警（如节点离线、资源不足等），在后台「告警设置」中配置。每个渠道可独立启用，告警时会并发推送到所有已启用渠道。

支持发票功能吗？

支持，默认关闭。开启后用户可以在面板中申请发票、管理发票抬头。管理员可以在后台审核和处理发票申请。发票功能有最低申请金额限制（默认 100 元，可在后台配置）。

管理员能导出数据吗？

可以。管理员可以导出以下数据（支持 CSV 和 Excel 两种格式）：

• 用户列表
• 订单列表
• 支付记录
• 操作日志

导出功能内置了公式注入防护，确保数据安全。

如何更改后台管理路径？

默认管理后台路径为 /admin。如果需要更改（如出于安全考虑），修改 config.yaml 中的 admin.path：

admin:
  path: my-secret-panel  # 管理入口变为 /my-secret-panel/login

修改后重启服务生效。前端会自动适配新路径。

未支付的订单多久会被自动取消？

超过 24 小时未支付的订单会被自动取消。取消后不会影响用户的其他操作，用户可以重新下单。

可以使用 Caddy 代替 Nginx 吗？

可以。Caddy 的优势是自动申请和续期 SSL 证书，配置也更简洁。Caddyfile 示例：

panel.example.com {
    reverse_proxy localhost:8080
}

Caddy 会自动处理 WebSocket 转发和 HTTPS，无需额外配置。

任务并发数怎么配置？

通过 config.yaml 中的 task.workers 配置异步任务的并发数（默认 5）。这决定了同时能执行多少个创建实例、重装系统等异步任务。

建议根据服务器性能和管理的节点数量适当调整。设置过高可能导致节点请求积压，设置过低则任务排队时间变长。

日志级别怎么调整？

修改 config.yaml 中的 log.level，支持以下级别：

级别	说明
debug	最详细，输出所有调试信息
info	默认级别，输出常规运行信息
warn	仅输出警告和错误
error	仅输出错误

日志格式通过 log.format 控制：text（彩色终端输出，适合直接查看）或 json（结构化 JSON，适合日志采集系统如 ELK、Loki）。

对象存储有什么用？

Novaix 支持对接 S3 兼容的对象存储（如 MinIO、阿里云 OSS、AWS S3 等），用于：

• 镜像归档：将不常用的镜像和 ISO 文件从本地磁盘转移到对象存储，节省服务器空间
• HA 共享存储：多实例部署时共享镜像文件

对象存储在后台「存储设置」中配置。归档到对象存储是异步操作，期间镜像仍可正常使用。

更新通道是什么？

Novaix 支持两个更新通道：

• stable（默认）：稳定版，经过充分测试，推荐生产环境使用
• dev：开发版，包含最新功能但可能不稳定，仅用于测试

更新通道在后台「高级设置」中配置。系统检查更新时会根据通道过滤版本——stable 通道只显示正式版本，dev 通道会同时显示预发布版本。

货币和时区怎么设置？

在后台「系统设置」→「区域」中配置：

• 货币代码：ISO 4217 标准代码（如 CNY、USD、EUR）
• 货币符号：显示在价格前面的符号（如 ¥、$、€）
• 时区：系统使用的时区，影响日期时间显示

金额在系统内部以分为单位存储（整数），展示时自动换算为元。

用户快照有数量限制吗？

系统层面没有硬性的快照数量限制。但快照会占用节点的磁盘空间，建议通过节点的存储容量间接控制。管理员可以通过任务日志监控快照的创建和删除情况。

什么是 external_url？不配会怎样？

server.external_url 是 Novaix 对外服务的完整 URL（如 https://panel.example.com），用于：

• 生成邮件中的链接（如密码重置链接、工单通知链接）
• OAuth 回调地址拼接
• 支付回调地址拼接
• 前端资源引用

如果不配置或配置错误，上述功能中的链接会指向错误的地址，导致邮件链接无法打开、OAuth 登录失败、支付回调失效等问题。生产环境必须正确设置。

主题和品牌自定义有什么区别？

• 主题：控制面板的整体外观风格，通过上传 .zip 主题包或从主题市场安装。可以切换活跃主题或恢复默认
• 品牌自定义：控制 Logo、Favicon、站点名称等品牌元素，通过后台「品牌设置」上传管理。需要授权版

两者相互独立，可以同时使用。外观自定义只能通过主题包实现，目前不支持直接注入自定义 CSS/JS 代码。

Novaix 支持多语言吗？

目前不支持界面多语言切换，所有界面文案为中文。后台「区域设置」中的配置仅影响货币显示和时区，不涉及 UI 翻译。

日志没有自动轮转怎么办？

Novaix 不内置日志轮转功能，日志输出到 stdout/stderr。如果通过 systemd 管理，journald 会自动处理日志存储和轮转。如果通过 Supervisor 管理并将日志写入文件，建议配置 logrotate：

/var/log/novaix/*.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    copytruncate
}

encryption_key 没有设置会怎样？

如果未单独配置 security.encryption_key，系统会自动从 jwt.secret 派生一个加密密钥。虽然功能上可以正常使用，但生产环境建议独立设置，以降低密钥泄露风险。

一旦有敏感数据（节点 SSH 密钥、实例密码等）被加密存储后，不可更改 encryption_key，否则已加密的数据将无法解密。

在线更新期间服务会中断多久？

在线更新分为两个阶段：

1. 下载阶段：在后台下载安装包并校验，不影响服务
2. 应用阶段：进入维护模式 → 备份数据库 → 执行迁移 → 替换二进制 → 启动新版本

服务中断仅发生在应用阶段，通常为数秒到数十秒，取决于数据库迁移的复杂度。如果新版本连续启动失败超过 3 次，系统会自动回滚到旧版本。

工作目录下有哪些重要文件？

默认工作目录 /opt/novaix 下的主要文件和目录：

路径	说明
config.yaml	配置文件
novaix.db	SQLite 数据库文件（使用 SQLite 时）
data/images/	镜像和 ISO 文件
data/uploads/	CMS 上传文件
data/plugins/	插件文件
data/themes/	主题文件
data/license.cert	授权证书缓存

WARNING

备份时请确保包含整个工作目录。特别是 config.yaml 和数据库文件，丢失后无法恢复。

数据库连接池怎么配置？

连接池参数仅对 MySQL 和 PostgreSQL 生效（SQLite 强制单连接）：

database:
  max_open_conns: 25    # 最大打开连接数
  max_idle_conns: 10    # 最大空闲连接数
  conn_max_lifetime: 3600  # 连接最大存活时间（秒）

默认值适合大多数场景。如果并发量较大或遇到连接超时，可以适当调高 max_open_conns。

授权到期后会怎样？

授权到期后，授权版独有的功能（如 VPC、代理系统、共享 IP 等）会被禁用，但核心功能（创建实例、管理节点等）仍可正常使用。续费授权后功能立即恢复。

如果授权服务暂时不可达（如网络波动），系统会保持当前状态不受影响，直到下次验证成功或确认授权失效。系统每 8 小时自动刷新授权状态，无需手动操作。

创建虚拟机失败，提示节点不支持虚拟机？

Novaix 在节点同步时会检测虚拟机（QEMU）支持状态。如果提示「该节点不支持虚拟机」，通常是以下原因：

1. QEMU 未安装：节点服务器上没有安装 QEMU。正常情况下初始化节点时会自动安装，如果安装失败请手动安装。
2. QEMU 安装后未重启服务：QEMU 安装后需要重启运行环境才能检测到虚拟机能力。重新初始化节点或手动在节点上执行 systemctl restart incus（OpenRC 使用 rc-service incus restart），然后在 Novaix 中同步节点即可。
3. 硬件不支持：节点服务器 CPU 不支持硬件虚拟化（缺少 /dev/kvm），或运行在不支持嵌套虚拟化的虚拟机中。

排查步骤：

# 检查 QEMU 是否安装
command -v qemu-system-x86_64 || command -v qemu-system-aarch64

# 检查运行环境是否识别到虚拟机 driver
incus query /1.0 | grep driver
# 正常输出应包含 "lxc | qemu"

# 如果 driver 中没有 qemu，重启服务后重试
systemctl restart incus

确认节点环境正常后，在 Novaix 管理面板中对该节点执行「同步资源」，系统会重新检测虚拟机支持状态。

虚拟机创建/重装特别慢？

虚拟机的创建和重装速度与节点的存储后端密切相关。Novaix 初始化节点时会自动按优先级选择存储后端：ZFS > btrfs > LVM > dir。

如果您的节点使用的是 dir 存储后端，虚拟机操作会非常慢（每次创建/重装都要写入完整磁盘大小的裸文件）。可以通过以下命令确认：

incus storage list

如果输出中 DRIVER 列显示 dir，建议迁移到 ZFS：

# 安装 ZFS
apt install -y zfsutils-linux

# 创建 ZFS 存储池
incus storage create zfs-pool zfs

# 停止所有实例
incus stop --all

# 逐个迁移实例到新存储池
incus move <实例名> --storage zfs-pool

# 修改 default profile 使用新存储池
incus profile device set default root pool=zfs-pool

# 启动所有实例
incus start --all

迁移完成后在 Novaix 后台同步节点即可。使用 ZFS 后创建和重装速度会从数分钟缩短到数秒。