升级迁移

本章说明从旧版本升级到 v1.1.x 后的数据变化和备份建议。

升级前备份

升级前请备份整个 conf 目录：

cp -a conf conf.bak.$(date +%Y%m%d%H%M%S)

Docker 部署时备份挂载目录，例如：

cp -a /opt/nps/conf /opt/nps/conf.bak.$(date +%Y%m%d%H%M%S)

数据文件

NPS 仍使用 JSON 文件持久化，默认位于 conf 目录。

每个对象文件使用 *#* 分隔多条 JSON 记录，这是当前项目的既有格式。

用户自动迁移与旧客户端恢复

v1.1.1 已新增 users.json。服务启动时会自动执行一次兼容迁移；升级到 v1.1.2 及后续 v1.1.x 时会继续保留该文件和已有用户关系：

1. 扫描所有客户端。
2. 如果客户端的 UserId 指向现有用户，保留该归属。
3. 如果 UserId 已失效，但旧 WebUserName / WebPassword 与现有用户完全匹配，修复为该用户的 ID。
4. 如果客户端没有 UserId，同样会优先复用完全匹配的现有用户。
5. 仅当整个 users.json 不存在时，才会依据旧客户端凭据创建新 User；文件已经存在时不会因旧字段复活被删除的账号。
6. 保存 users.json 和更新后的 clients.json。

冲突处理：

• 同名同密码：合并为一个用户。
• 同名不同密码：新用户名为 原用户名_客户端ID。

迁移失败不会影响主流程，旧客户端登录仍保留兼容。

如果升级时整个 users.json 因为未挂载数据卷而缺失，服务会仅依据仍保留 WebUserName / WebPassword 的历史客户端，恢复对应的启用用户并写回新的 users.json。这是为了让旧版 NPC 无需重新配置即可恢复连接。

该恢复只会在 users.json 完全不存在 时执行：文件存在但用户被删除、停用、到期 或到期时间格式不正确时，服务仍会拒绝该客户端连接，不会自行重新启用被撤销的账号。

升级步骤

二进制部署

# 停止旧服务
nps stop

# 备份 conf
cp -a conf conf.bak.$(date +%Y%m%d%H%M%S)

# 替换 nps/npc 二进制
# 启动服务
nps start

Docker 部署

cd /opt/nps
docker compose pull
docker compose up -d
docker logs nps --tail=100

升级后检查

1. 登录管理员面板。
2. 打开「用户管理」，确认旧客户端账号是否已迁移为用户。
3. 打开「客户端」，确认客户端显示了所属用户。
4. 使用普通用户账号登录，确认只能看到分配给自己的客户端。
5. 新增一个普通隧道或 Host 规则，确认配额逻辑符合预期。
6. 若旧 NPC 仍提示验证失败，检查容器挂载的 /conf 是否同时保留了 clients.json 和 users.json，并查看服务端日志中的具体拒绝原因。

回滚

如果需要回滚：

1. 停止当前服务。
2. 恢复旧二进制。
3. 恢复备份的 conf 目录。
4. 启动旧服务。

users.json 是 v1.1.1 新增文件，旧版本不会使用它。升级时不要删除该文件。