产品化体系总览

SN（Sequence Number / 许可管理中心，sn.thinkalike.com.cn）是英同科技 全系列软件产品的大管家：把所有产品的交付、授权、更新与补丁 收归一处、统一管理，即「统一交付与授权中枢」。它把「一个软件产品要上线服务客户」 所需的全部内核能力收敛到一个后台：产品登记、离线签名授权、一键安装包、发布包与补丁管理、 部署台账、远程提醒与一键更新——没有任何产品各自维护私有更新器。所有产品共用同一套机制， 接入新产品只需在后台配置一条记录。

一个产品的完整生命周期

产品家族

当前在架 AIRPA（紫光智能体平台）、THINKDE、 THINRPA（企业级 RPA）、RMS（Think RMS 一体化资源监控平台）等， 每个产品是一条 products 记录，由启动播种链幂等建立，代码即 SN 前缀、 安装目录/服务名前缀、环境前缀，天然隔离；接入新产品只需加一条记录（见「接入新产品指南」）。

为什么用「离线签名 + 心跳台账」双轨

授权侧坚持离线可验证：产品端只依赖内置公钥校验 Ed25519 签名， 断网也能运行已签发的许可，SN 服务不在关键路径上。更新侧才用在线心跳： 探针只负责「问一句有没有新版」，网络不通就静默等下个周期，绝不因此影响业务运行。 两者解耦，任何一条通道故障都不会拖垮另一条。

统一更新治理（大管家模型）

为什么是「大管家」

传统做法里，每个产品各自写一套升级脚本、各自维护版本源、各自盯补丁，多产品就变成 多套互不相通的更新逻辑——难观测、难审计、易失控。SN 的定位是把这层职责上收： 所有产品的更新与补丁机制统一由 SN 治理，产品端不再自建更新器。端上只保留一个 由 SN 按产品渲染的极薄探针，控制面（发布、清单、台账、提醒、回滚策略）全部集中在 SN。

被「收纳统一」的六个面

统一的一键更新入口

不论哪个产品，升级都是同一条形态的命令： curl -fsSL "https://sn.thinkalike.com.cn/update.sh?product=<CODE>" | bash。 SN 只负责下载→校验 SHA256→定位包内 install-patch.sh→执行→上报， 不关心补丁内部如何替换文件——这层职责由各产品自己的 install-patch.sh 承担。

治理边界（SN 与产品如何解耦）

• 核心包「出什么」属各产品研发；SN 只管「怎么发、怎么更、怎么管」这一层， 不侵入任何产品的业务代码。
• 产品侧只需做两件事：① 遵守 install-patch.sh 补丁规范； ②（可选）读端上提醒标记、接一个「一键更新」按钮，即可获得完整的远程提醒与升级能力。
• 新产品的接入边际成本≈「一条 products 记录 + 一个合规补丁包」，无需重造更新链。

一句话：SN 把所有产品的更新与补丁「收上来统一管」，把执行「按规范放回去」， 从而获得一致的版本可观测、统一的提醒/推送/回滚、集中的审计，以及极低的接入成本。

SN 平台机制

技术栈与拓扑

单进程 FastAPI 服务 + SQLite 持久化（裸 sqlite3，无 ORM），监听 127.0.0.1:8401，由 nginx 反向代理到 sn.thinkalike.com.cn。 管理台是纯静态 static/sn.html（零构建、原生 JS），在线文档由 app/docs.py 同源渲染。没有外部数据库、消息队列或缓存依赖 —— 一台小 ECS 即可承载全系列产品的交付。

数据模型

deployments 的身份键是 (product_code, instance)， instance 由端上机器指纹派生（sha256(fingerprint+product) 前 16 位）， 同一台机器重复心跳只更新、不新增行。

清单同步与热加载

启动时读 downloads/manifest-*.json，对 release_files 全删全插 —— 清单是唯一事实源。因此补丁上架用 register_release.py 写清单而非直接改库（直接改库重启即丢）。上架后可调 POST /api/releases/reload 让运行中的服务重读清单，免 systemctl restart， 端上下个心跳周期就能看到新补丁。

配置与密钥（环境变量 / .env）

鉴权三通道

公开端点（/api/activate、/api/trial、/api/deployments/check、 /guide、/install.sh、/update*.sh、/download/*）无需登录， 其中 check 带源 IP 频控、激活门控；脚本与下载页本就公开，不含机密。

安全模型

离线可验证的授权链

授权信任不依赖 SN 服务常在线：Ed25519 私钥只存服务端（SN_SIGN_KEY）， 客户端内置公钥离线验签。.lic / 离线激活码的载荷先经 AES-256-GCM 混淆 （口令 SN_AES_PASSPHRASE，PBKDF2 派生）再签名——既防读又防篡改。 客户端拿不到私钥，也就伪造不了一枚合法许可。

多把令牌职责隔离（最小权限）

公开面与防滥用

• 脚本（/install.sh、/update*.sh）与下载页公开，但不含任何机密；
• /api/deployments/check 公开但带源 IP 滑动窗口频控 + 激活资格门， 响应剔除台账管理字段（customer/note）；
• 伪造 SN / 未激活裸装只答「有没有新版」，绝不落库污染台账；
• prod 启动强制校验机密项非空；dev 用临时密钥并显式告警；
• 口令、密钥、真实哈希值永不写进前端页面与本在线文档。

威胁模型：SN 服务与签名密钥在企业可信边界内；客户端为不信任环境， 因此只下发公钥与验签逻辑，任何可验证产物（.lic/离线码）都带防篡改签名。

授权机制

序列号（SN）

SN 是可读、可核对的授权主体，格式 <PRODUCT>-XXXX-XXXX-XXXX， 字母表剔除易混字符 0O1I（防手抄错）。一枚 SN 携带：客户名、有效期、 配额（max_servers 服务器数、max_cpus/max_gpus 算力，0=不限、 max_users 用户数）、状态（active/disabled）、是否试用、绑定的机器指纹。

在线激活（联网环境）

产品端调用 POST /api/activate，提交 {sn, fingerprint}； 服务端校验 SN 有效、未停用、未过期后，返回一段签名许可 lic。 首次激活绑定机器指纹：之后同一 SN 只能在同一台机器重新激活，换机被拒 （该 SN 已绑定其他服务器）。产品端用内置公钥离线验签，验过才放行。

离线许可 .lic（断网环境）

对无法联网的客户，管理台按 SN 手工签发 .lic （POST /api/sn/{id}/lic）。.lic 是把授权载荷（SN、产品、客户、 有效期、配额、指纹、签发时间）用 Ed25519 私钥签名 + AES-256-GCM 混淆后的密文， 客户导入产品即可离线激活，产品端公钥验签防篡改。私钥只存服务端，客户端拿不到也伪造不了。

离线激活码（用户中心自助）

OFFLINE1.<payload>.<sig> 形态，同样 Ed25519 自签名。供会员在用户中心 （uc 经内部令牌转调 POST /api/sn/{id}/offline-code）自助复制粘贴激活， 无需产品端联网回连 SN。

试用（Trial）

不带 SN 的一键安装会调 POST /api/trial 现场领一枚限时试用 SN （时长按产品 trial_days，指纹留空、首次激活才绑机）。公开整包下载 /bundle/<code> 每次下载都现签一枚全新试用 SN 内嵌进安装包， 相互独立。试用 SN 可「续期」（在原有效期上顺延）或「转正式」（清试用标记、给正式期）。

配额与有效期语义

安全边界：SN 服务只在「签发/激活」一刻参与，运行期产品离线自校验， 所以 SN 服务临时不可用不会导致已激活客户停机；反之更新检查失败也绝不影响业务运行。

产品配置界面

管理台「产品与打包」页把产品从登记到可安装的全流程收敛在一个界面。字段与后端 products 表一一对应：

在线打包与一键安装

产品配置好后，「发布包管理」上传核心包或登记补丁；「一键安装」区即时渲染出该产品的 安装命令与可下载 install.sh。加载器会：拉取发布包 → 校验 SHA256 → 解压到安装目录 → 生成 systemd 服务 → 激活（带 SN 则正式，无 SN 且允许则试用）→ 植入更新探针 （写 cron，纳入部署台账）。管理员还可用「整包下载 fullpkg」把小包 + 内嵌试用 SN 打成一柜交付包。

说明书页（/guide）

每个产品有公开说明书页 /guide?code=<CODE>（ThinRPA 另有干净别名 /ThinkRPA），含一键安装命令、离线包下载、部件清单、更新记录，以及 「自动更新代理」段（探针与一键升级用法）。它是给客户看的操作手册，随配置实时渲染、不留占位符。

已部署环境的连接与推送

连接模型：端上主动拉，SN 不推

SN 不主动向客户机发起连接（客户机多在内网/NAT 后，也出于安全不应被外部拨入）。 「推送」通过端上探针定时拉 + 台账标记实现：补丁一上架，各端下个心跳周期 自然发现，产品内弹提醒。这是纯 HTTP、单向、幂等的模型，不依赖微信/短信可达性。

心跳与注册（POST /api/deployments/check，公开+频控）

• 请求体带 {sn, instance, version, hostname, fingerprint, action}；
• 激活资格门：只有 SN 存在、active、未过期且产品匹配时才写台账—— 伪造 SN、未激活裸装只答「有没有新版」，绝不落库污染台账；
• 响应只回公开字段（补丁元数据 + 下载地址），台账管理字段（customer/note）一律不外泄；
• 源 IP 滑动窗口频控（默认 60 次/60 秒），防爬防滥用。

升级结果上报（POST /api/deployments/report，管理令牌）

update.sh 升完用 SN_ADMIN_TOKEN（存于端上配置，chmod 600）Bearer 上报； 写 update_ok/update_fail 事件。台账与事件流在管理台「部署台账」页可见。

事件流（update_events）

运营视角的「推送」闭环

1. 出补丁 → register_release.py 上架 + 热加载；
2. 「部署台账」自动把受影响台标黄为「待更新」（按版本比对）；
3. 需人工触达时，按台账的客户/SN/IP/主机反查联系人，发通知；
4. 客户在自己终端跑 update.sh（或产品内按钮）完成升级 → 事件回流台账 → 标黄转绿。

试点策略：先在补丁链最成熟的 THINKDE 打通「探针接入 + 产品内提醒条」全闭环， 再按同一模板批量接入其它产品——机制在 SN 侧是全量的，产品侧只需读提醒标记 + 接一个升级按钮。

接入新产品指南（分步）

把一个已有软件产品接入 SN 的完整清单——机制全在 SN 侧，产品侧几乎零侵入：

1. 出包：产出核心包 <code>-core-<ver>.tar.gz 与 downloads/manifest-<CODE>.json；
2. 登记产品：后台「产品与打包」新建：代码（=SN前缀/目录前缀）、名称、安装目录、 服务名、端口、试用天数、（可选）extra_setup 与 page_slug（公开发布页短链， 留空按名称自动派生）；
3. 上架核心包：上传 pkg 或走发布链生成清单；
4. 发布记录（必走）：产品仓库维护 CHANGELOG.md 并用 seed_changelog.py 灌库，或在后台「发布记录」页签直接录入 —— 前台发布页 /release/<slug>（产品登记即自动生成）以发布记录为 数据源，没有记录的客户页就是空账；
5. （可选）登记补丁：register_release.py 上架，包内必须带 install-patch.sh；
6. 约定健康端点：产品的 /api/health 返回 JSON 里带 version 字段， 探针就能自动读到当前版本（否则回退安装目录 VERSION 文件）；
7. 签发与分发：生成 SN / 拿一键安装命令 curl .../install.sh?product=<CODE> | bash 发给客户；
8. 自动成环：客户装完，探针自动植入 cron → 注册进台账 → 后续补丁上架即进“提醒→更新”闭环。

产品侧可选：升级提醒条（M2）

要让客户在产品管理界面里看到“有新版”，产品 UI 只需读探针写的标记文件 /var/lib/<code>-update/update-available（key=value 文本），非空则弹横幅， 附一个“一键更新”按钮执行 curl -fsSL '.../update.sh?product=<CODE>' | bash。 /update-probe.sh、/update.sh 都按产品自动渲染，无需为每个产品单写脚本。

发布与更新机制

发布部件：核心包 vs 补丁

补丁上架链（register_release.py）

一条命令把补丁包登记进 downloads/manifest-<CODE>.json： register_release.py <patch.tar.gz> --product THINKDE --version 0.2.1 [--sha256 ...] [--retire 旧包] [--dry-run]。要点：

• SHA256 传输对账：本地重算哈希与登记值不符即中止、清单原样不动，杜绝把坏包推给客户；
• 上新不撤旧：每版补丁都留在页面供回看与单独取包；确需收回发错的包才用 --retire（只去登记、不删磁盘文件，已发出的链接仍可下载）；
• 补丁不改核心版号：manifest.version 保持核心版本，补丁版本只标在补丁条目上；
• 写清单前自动留 .bak-<时间戳> 备份；
• 写完调 POST /api/releases/reload 热加载，运行中的服务立即读到新补丁，免重启。

升级补丁统一规范（standard）

为支撑「一键更新」，所有补丁包必须在顶层目录内自带 install-patch.sh （校验哈希→备份→替换→重启→验版本→失败回滚）。register_release.py 在新登记时强校验： 解包看内容，缺 install-patch.sh 直接拒绝上架。历史已登记的包重跑不追溯拦截。 端上 update.sh 升级时直接调这个包内脚本，SN 不关心每个产品的补丁内部逻辑。

部署台账与状态

端上探针心跳写进 deployments；管理台按 (产品×状态×搜索) 查看，每条算 update_state：pending（有更新补丁未装）、latest（已最新）、 unknown（未上报版本）、retired（已退出台账）；online=30 天内有心跳。 可按 SN 反查客户人工通知，也可一键复制该台的升级命令。

系统更新（一键升级）

两个端上脚本

两者都由 SN 按产品实时渲染（GET /update-probe.sh?product=<CODE>、 GET /update.sh?product=<CODE>），与 /install.sh 同等公开面（脚本不含机密）。

极薄探针：零依赖

探针只用 curl + sed + grep 解析 SN 返回 JSON 的顶层标量键， 不依赖 jq/python；一轮一个请求，失败静默退出等下个周期，绝不在客户机上报错刷屏。 发现新版时写 /var/lib/<code>-update/update-available 标记（key=value 文本）， 产品 UI 读它弹升级横幅；响应为空（网络不通/SN 维护）保持现状不碰标记。

一键升级流程（update.sh）

# 在目标机 root 终端执行（或产品管理页的「一键更新」按钮）：
curl -fsSL "https://sn.thinkalike.com.cn/update.sh?product=<CODE>" | bash

1. 探当前版本（健康接口 JSON 的 version 字段 > 安装目录 VERSION 文件 > unknown）；
2. 向 /api/deployments/check 问有没有新版；无则提示已最新并退出；
3. 有则下载补丁到临时目录，本地重算 SHA256 与登记值比对，不符即丢弃不装；
4. 解包，在包内定位 install-patch.sh（找不到=不合规，丢弃不装）；
5. 在子 shell 里执行 install-patch.sh（自带备份与失败回滚）；
6. 成功上报 update_ok、失败上报 update_fail（走 /api/deployments/report，带管理令牌）， 上报失败不阻断升级，只丢一条台账事件。

离线/内网环境

连不上 SN 的客户按说明书页手动下载补丁包（下载地址本就公开在 /guide）， 校验 SHA256 后自行执行包内 install-patch.sh。机制不强制联网，联网只是让 「发现新版」自动化。

离线交付与采集

客户环境分三档，交付链对每一档都闭合：

离线采集脚本 fetch-all.sh

管理台「发布包管理」的「下载离线采集脚本」（GET /api/releases/fetch-script） 拿到一个按清单批量拉包的脚本：在任一联网机执行，按 manifest 断点续传 + SHA256 校验 下载全部部件，产出可烧录/拷贝到内网的目录。把“SN 上有什么”原镜一柜地搬到隔离网。

整包与一柜交付

• /bundle/<code>：公开整包，每次下载现签一枚全新试用 SN 内嵌进安装包；
• fullpkg（管理员）：安装向导加载器 + 核心包 + 内嵌试用 SN 打成一柜交付包；
• 离线激活：断网客户用管理台签发的 .lic 或用户中心自助的 OFFLINE1.* 离线码，导入产品本地验签。

离线环境的更新：连不上 SN 时探针静默跳过（不影响业务）；要升级时按 说明书手动下载补丁包、校验 SHA256 后执行包内 install-patch.sh。

公开发布页与发布记录

每个产品一个公开发布页（注册即自动生成）

每个产品都有独立的公开发布页 /release/<slug>：一键安装/离线采集、部件清单、 升级补丁、装后自检、发布记录、试用转正六段一页（与 /guide?code=<CODE> 同一渲染器，短链更干净）。slug 默认按产品名称自动派生（「Think RMS 一体化…」的前导 ASCII 词 → /release/ThinkRMS；中文名派生不出别名时回退产品代码）， 也可在后台产品编辑里用 page_slug 显式指定。产品登记进后台那一刻起 页面就存在，不需要为任何产品单独写一条路由。

发布记录（changelogs）的两条录入通道

• 批量灌库：scripts/seed_changelog.py 解析产品仓库的 CHANGELOG.md（## vX.Y.Z（YYYY-MM-DD） + ### 分区 + - 条目 格式）幂等入库，支持 --dry-run / --strict / --prune；
• 后台手工：SN 控制台「发布记录」页签按产品查看/新增/编辑/删除 （GET/POST/DELETE /api/products/{id}/changelogs），保存即生效 —— 前台页每请求现读库，免重启。

前台发布页只展示最近 30 条并注明总数口径；后台接口不受该上限约束。

团队铁律：任何新增产品都必须走 SN 的更新与发布机制 —— 登记产品、上架发布部件、灌入发布记录、写 manifest-<CODE>.json 清单—— 四步缺一不算发布完成。 发布记录为空的产品页，客户看到的「共 0 个版本」就是接入不达标的直观证据。

故障排查

日志入口：服务端 journalctl -u sn -n 200；端上探针 /var/log/syslog （cron）与 /var/lib/<code>-update/ 状态目录。

API 接口参考

基址 https://sn.thinkalike.com.cn。除标注「公开」外，/api/* 管理接口 需登录会话（Cookie 或 Bearer），部分支持内部/管理令牌。

健康与鉴权

授权（产品端调用）

SN 管理

产品与发布

更新与台账

公开页与下载