﻿================================================================
宇珩安全管控系统 · 上线与远程升级操作卡
给厂商/交付人员用的一张纸：从零到"客户拿到就能用、以后自己升级"
================================================================

先说结论，整套流程只有三件事：

  ① 注册一个免费域名（一次，约 5 分钟）
  ② 填一张客户表，跑一条命令 → 每家一个专属安装包
  ③ 以后发新版，再跑一条命令 → 客户自己弹窗升级

客户那边永远只做两步：解压、双击安装。装完开机自动运行。
客户不需要配路由器、不需要填地址、不需要懂"域名""令牌""端口"。

----------------------------------------------------------------
一、域名：你只需要做一次的 3 步
----------------------------------------------------------------

为什么必须有域名：手机在外地用流量访问，得有一个"永远不变"的地址。
IP 会变（宽带重播号、换机房），域名不会变。客户扫的那张二维码里就是它。

【1】注册（唯一需要你本人操作的一步，因为要收邮箱验证码）

  打开 https://dynv6.com  → Sign up
  填邮箱 + 密码 → 去邮箱点确认链接
  （免费，不需要信用卡，不需要实名）

【2】建一个自己的域名

  登录后点 Create Zone
  名字随便起，比如： yhpower
  系统会给你： yhpower.dynv6.net
  这个就是你的"主域名"，所有客户都挂在它下面。

【3】生成 API 令牌

  右上角账号 → Keys → Create Key
  复制那串令牌（很长，一次性显示，存好）

然后回到程序目录，一条命令把客户子域名全建出来：

  先预览（不会改任何东西）：
  node tools/dns.js --token 你的令牌 --zone yhpower.dynv6.net --ids C001,C002,C003

  确认没问题，真的建：
  node tools/dns.js --token 你的令牌 --zone yhpower.dynv6.net --ids C001,C002,C003 --apply

它会给每个客户建一条解析：
  c001.yhpower.dynv6.net
  c002.yhpower.dynv6.net
  ……

地址先填的是占位值，客户机开机后每 5 分钟自己上报真实 IPv6，你不用管。

  小提示：
  · 想更好看，加 --prefix yh- ，子域名就变成 yh-c001.yhpower.dynv6.net
  · 想用自己的品牌域名（xxx.com），见文末附录 B
  · 令牌只存在你本地，不进安装包；安装包里每个客户只带自己那一条的记录名+令牌

----------------------------------------------------------------
二、给客户出安装包：填一张表，跑一条命令
----------------------------------------------------------------

【1】准备客户表

  把 customers.sample.csv 复制成 customers.csv，用 Excel 打开填。
  一行一个客户，列的含义：

    编号       C001（大写字母数字，会显示在客户开机大屏上）
    客户名称   ××供电公司（客户大屏上显示的就是它）
    接入方式   ipv6（默认，数据不经过第三方）/ tunnel（走中转）/ auto（自动判断）
    对外地址   https://c001.yhpower.dynv6.net
    DDNS记录   c001.yhpower.dynv6.net
    DDNS令牌   填你刚才那个 dynv6 令牌（每行都要填）
    隧道令牌   只有 tunnel 模式才填
    售后电话   138-0000-0000（显示在客户大屏底部）
    更新源     留空则用命令行 --update-url 的值

【2】出包

  node tools/factory.js --csv customers.csv --update-url https://你的更新地址/update

  第一次会自动打一次完整包（约 1 分钟），之后每个客户包几秒钟。

  产出：
    dist\交付包\C001-××供电公司.zip    ← 直接发微信/拷U盘给客户
    dist\交付包\交付清单.csv           ← 这一批的记录，留档

  包里已经写好这个客户专用的：单位名称、访问地址、动态域名令牌、售后电话、更新源。
  客户拿到的是"成品"，不是"工具"。

  只想重出某几家（比如地址填错了）：
  node tools/factory.js --csv customers.csv --only C003,C007 --update-url ...

----------------------------------------------------------------
三、客户那边：两步，一分钟
----------------------------------------------------------------

  1. 解压到他电脑（D 盘，路径别带空格最稳）
  2. 双击「② 安装成电脑应用.bat」

  装完会发生：
    · 桌面/开始菜单出现图标
    · 装进开机启动 —— 以后开机自己跑，不用每天点
    · 自动打开一个大屏页面：客户名称 + 二维码 + 三步说明 + 你的售后电话

  手机：微信扫那个码 → 打开就能用（不用装 App、不用注册）
  人在外地、用流量也能用 —— 这就是域名的作用。

  提醒客户：装的时候杀毒软件可能弹窗，选「允许」/「信任」。

----------------------------------------------------------------
四、以后发新版：一条命令，客户自己弹窗
----------------------------------------------------------------

  改完代码，改一下 server.js 里的 VERSION（例如 2.8 → 2.9），然后：

  node tools/release.js --notes "修复抓拍偶发丢失" --notes "手机端支持横屏"

  --notes 写几条都行，客户在弹窗里看到的就是这几句，别写代码术语。

  它会生成两个文件：
    dist\update\version.json
    dist\update\upgrade-2.9.zip

  把这两个文件放到你的"更新地址"（见第五节），就完事了。

  客户机上的表现：
    · 2 分钟内自动查到新版
    · PC 端直接弹窗：当前版本 → 新版本 + 更新说明 + 「立即更新」
    · 点一下，20~60 秒装完，页面自己回来
    · 台账、抓拍照片、录像、证书、账号 —— 一律不动
    · 不想现在装：点「稍后再说」（24 小时内不再弹）
    · 这个版本不想要：点「这个版本不再提示」（下个版本还会弹）

  升级包只带程序文件，一般 1~5 MB，客户那边下载很快。

  装失败会自动回滚：覆盖前先备份 server.js 和 public，出错就还原，
  日志写在程序目录的「更新日志.txt」。

----------------------------------------------------------------
五、更新地址放哪儿：三个选择
----------------------------------------------------------------

  A. 放你自己的电脑（零成本，推荐先用这个）
     你的电脑已经有固定域名了（第一节那个），把 dist\update\ 里的两个文件
     复制到程序目录的 update\ 文件夹即可。
     地址就是： https://c001.yhpower.dynv6.net/update
     前提：你这台机器开着。（客户查不到只会静默跳过，不影响使用）

  B. 对象存储（推荐正式用）
     腾讯云 COS / 阿里云 OSS，开一个公共读的存储桶，
     传 version.json 和 upgrade-x.x.zip，用它的 HTTPS 访问地址即可。
     一年几十块，比自建稳，你关机也不影响客户升级。

  C. 一台轻量云服务器
     客户多了以后最省心的做法，还能顺便做远程协助（见附录 C）。

  三者可以随时换：改 customers.csv 的「更新源」列，重出包即可。
  老客户换地址不用重装 —— 让他在「账号 → 程序更新 → 更新源」里改一次。

----------------------------------------------------------------
六、交付现场验收 5 步（每次上门照着做）
----------------------------------------------------------------

  □ 1. 双击桌面图标，大屏出来了吗？客户名称对不对？
  □ 2. 手机连客户 WiFi 扫码，能进吗？
  □ 3. 手机**关掉 WiFi、只用流量**，再扫一次 —— 能进，异地访问才算通。
  □ 4. 电脑上「手机接入」里，通道显示在线、能看到手机画面吗？
  □ 5. 关掉程序，重启电脑 —— 等 1 分钟，手机再扫还能进吗？（验证开机自启）

  第 3 步不通，是客户网络拦了入站 IPv6：
    · 跑一次「放行IPv6端口.bat」（要管理员）
    · 还不行就登录光猫（一般 192.168.1.1），关掉「IPv6 防火墙 / IPv6 Session 保护」
    · 客户网络实在动不了：这家改用 tunnel 模式重出包（见附录 A）

----------------------------------------------------------------
七、常见问题
----------------------------------------------------------------

Q: 客户换电脑了怎么办？
A: 新电脑装同一个包（编号一样）。域名不变、手机扫的码不变，
   数据用旧的 data 文件夹覆盖过去即可。手机端什么都不用做。

Q: 客户重装系统 / 换了宽带，地址会变吗？
A: 域名不变。程序开机自己上报新 IP，最多 5 分钟生效。

Q: 客户说"没有弹窗"？
A: ① 先确认更新地址能打开（浏览器访问 地址/version.json 看有没有内容）
   ② 确认 version.json 里的 version 比客户那台大
   ③ 客户机「账号 → 程序更新」点「查看更新」手动查一次，看报什么错

Q: 弹窗里能不能强制升级？
A: 能。version.json 里加 "mandatory": true，前端会把「稍后再说」藏起来。
   （谨慎用，施工高峰期别强制重启）

Q: 升级会不会把台账弄丢？
A: 不会。升级只覆盖程序文件，data / photos / videos / certs 全部跳过，
   而且覆盖前会备份、失败自动回滚。

Q: 一次能给多少客户？
A: 表里多少行就出多少个包，没有数量限制。一个 dynv6 域名挂几百个子域名没问题。

----------------------------------------------------------------
附录 A：客户网络动不了，改用 tunnel 模式
----------------------------------------------------------------

  这种方式数据经 Cloudflare 中转，不需要客户放行任何端口，
  但要自己的域名（dynv6 的免费子域名不能挂 Cloudflare）。

  1. Cloudflare 加你的域名 → Zero Trust → Tunnels → 建一个隧道
  2. 复制隧道令牌（eyJhIjoi... 那一长串）
  3. customers.csv 里这一行：接入方式写 tunnel，隧道令牌填进去
  4. 重出这个客户的包

  代价：走境外中转，速度一般；不建议作为默认方案。

----------------------------------------------------------------
附录 B：想用自己的品牌域名（xxx.com）
----------------------------------------------------------------

  1. 买域名（阿里云/腾讯云，.top/.xyz 一年十几块，.com 一年几十）
  2. 域名解析改成 Cloudflare 的 NS（免费套餐够用）
  3. 在 Cloudflare 里加一条 AAAA 记录：c001 → 客户机的 IPv6
     批量的话用 Cloudflare API（跟我提，我给你写对应的脚本）
  4. customers.csv 里对外地址写 https://c001.xxx.com

  好处：客户看到的是你的品牌，不像免费域名。
  注意：国内服务器的域名要备案；只是解析到客户自己的电脑，不涉及备案。

----------------------------------------------------------------
附录 C：客户多起来以后（10 家以上再考虑）
----------------------------------------------------------------

  现在这套是"每台客户机自己对外"，优点是不花服务器钱、数据不经第三方。
  客户超过 10 家、或者要求"你随时能远程看"的时候，可以加一台中转服务器：

    · 香港/国内轻量云（一年一两百）
    · 每家一个固定子域名，全部指到这台服务器，由它转发到各自的电脑
    · 好处：客户网络再烂也能通；你能统一看在线状态；升级包只放一处
    · 代价：多一台机器的钱，数据过中转

  真到那一步跟我说，我把服务端脚本和批量配置一起写好。

================================================================
一句话记住：域名你注册一次，客户表你填一次，以后每次发版一条命令。
================================================================
