From b613324c005e812f0e596c4ee4a99a5851b76dd4 Mon Sep 17 00:00:00 2001 From: wood911010 Date: Tue, 25 Nov 2025 00:57:41 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=93=8D=E4=BD=9C?= =?UTF-8?q?=E6=8C=87=E5=8D=97=E6=96=87=E6=A1=A3=E5=8F=8A=E5=85=B6=E9=93=BE?= =?UTF-8?q?=E6=8E=A5=E8=87=B3=E6=96=87=E6=A1=A3=E9=85=8D=E7=BD=AE=EF=BC=8C?= =?UTF-8?q?=E4=BB=A5=E6=94=AF=E6=8C=81=E7=94=A8=E6=88=B7=E5=AF=B9=E8=AE=B8?= =?UTF-8?q?=E5=8F=AF=E8=AF=81=E7=AE=A1=E7=90=86=E7=9A=84=E5=85=A8=E9=9D=A2?= =?UTF-8?q?=E7=90=86=E8=A7=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.mjs | 3 ++ docs/en/guide/operating_guide.md | 73 ++++++++++++++++++++++++++++++++ docs/guide/operating_guide.md | 72 +++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+) create mode 100644 docs/en/guide/operating_guide.md create mode 100644 docs/guide/operating_guide.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index d5a7141..ec815e4 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -34,6 +34,7 @@ export default withMermaid( items: [ { text: '介绍', link: '/guide/' }, { text: '快速开始', link: '/guide/getting-started' }, + { text: '操作指南', link: '/guide/operating_guide' }, { text: '许可证结构与验证（客户端要点）', link: '/guide/license-token-structure' }, { text: '商业价值', link: '/guide/business_value' }, { text: '接口文档', link: '/guide/api' }, @@ -59,6 +60,7 @@ export default withMermaid( items: [ { text: 'Introduction', link: '/en/guide/' }, { text: 'Getting Started', link: '/en/guide/getting-started' }, + { text: 'Operating Guide', link: '/en/guide/operating_guide' }, { text: 'Business Value', link: '/en/guide/business_value' }, { text: 'License Structure & Validation', link: '/en/guide/license-token-structure' }, { text: 'API Reference', link: '/en/guide/api' }, @@ -84,6 +86,7 @@ export default withMermaid( items: [ { text: 'Introduction', link: '/guide/' }, { text: 'Getting Started', link: '/guide/getting-started' }, + { text: 'Operating Guide', link: '/guide/operating_guide' }, { text: 'License Token Structure', link: '/guide/license-token-structure' }, { text: 'API 文档 | API Reference', link: '/guide/api' } ] diff --git a/docs/en/guide/operating_guide.md b/docs/en/guide/operating_guide.md new file mode 100644 index 0000000..37ddcf3 --- /dev/null +++ b/docs/en/guide/operating_guide.md @@ -0,0 +1,73 @@ +# Operating Guide + +## Usage Context + +This guide walks through the complete lifecycle of License Manager: “create license → distribute code → customer activation → heartbeat monitoring / renewal”. It targets operations, customer success, and implementation teams so they can master the key actions for online, offline, and hybrid deployments with minimal back-and-forth. + +## Terminology Recap + +- **License Code**: A unique identifier generated after configuring a license policy in the admin console. It defines validity period, max activations, feature set, and deployment mode. +- **License File / Key**: An encrypted artifact bound to a specific device fingerprint. Clients validate locally with this license during startup. +- **Hardware Fingerprint**: Machine identifiers (MAC, CPU serial, HostID, etc.) collected by the client or manually to prevent cloning. +- **Heartbeat**: Periodic status data reported by online/hybrid clients, enabling remote control, renewals, and auditing. + +## End-to-End Flow + +```mermaid +graph TD + A[Create License Policy] --> B[Generate License Code] + B --> C{Deployment Mode?} + C -->|Online/Hybrid| D[Customer enters code
+ auto activation] + C -->|Offline| E[Collect fingerprint
Generate license] + D --> F[Heartbeat monitoring & control] + E --> G[Local validation & manual updates] + F --> H[Renew / expand] + G --> H +``` + +1. **Create policy**: Capture customer profile, feature modules, validity, deployment mode, and activation cap. +2. **Distribute code / license**: Share the license code or offline license package depending on deployment mode. +3. **Customer activation**: The client bundles license code + fingerprint to exchange for a license, or loads an offline license directly. +4. **In-life management**: Monitor heartbeats, enforce revocations, trigger renewals, or increase capacity as needed. + +## Business Scenarios + +### Scenario 1: 7-day trial, customer deploys 100 servers (online mode) + +1. Create a license code with validity of 7 days, max activations 100, deployment mode “Online/Cloud”, and enable the trial feature set. +2. Share the code (e.g., `LIC-2266-EtgAHCyh8HJT-hTAA`) and instruct the customer to place it in the required directory or config file. +3. When the first server boots, the client reads the code and local fingerprint, then calls the REST API. The platform returns a license bound to that server. +4. The admin console shows “Activation progress 1/100” and records the fingerprint plus last seen time. +5. The 100th server repeats the same flow, bringing activation progress to 100/100. Any 101st activation attempt is rejected. +6. After 7 days the local validation fails, a renewal prompt appears, and operators can extend the validity or switch to a paid package. + +> **Tip**: Enable heartbeat alerts in online mode to capture usage signals during the trial window and surface upsell opportunities. + +### Scenario 2: Offline deployment, single server with perpetual license + +1. Create a license code with validity “Perpetual”, max activations 2, deployment mode “Offline”, and enable the contracted feature set. +2. Use a script or the License Manager offline collector to capture the server’s fingerprint and confirm accuracy with the customer. +3. In the console, open the “Offline License” workflow, select the license code, input the fingerprint, and download the generated license file. +4. Deliver the license to the customer so they can place it in the required directory (config folder, system variable, etc.). +5. The product now validates locally. If hardware changes, collect the new fingerprint and regenerate the license. + +> **Tip**: Because offline mode cannot detect device changes, outline the fingerprint change process in the contract to discourage unapproved transfers. + +### Scenario 3: Trial expires and the customer renews for one year (online / hybrid) + +1. Locate the customer’s trial license, update validity from “7 days” to “1 year”, and adjust features or activation caps if needed. +2. After saving, the system marks the license as “Pending Sync” and includes an update flag in the next heartbeat response. +3. The client sees the update signal, automatically downloads the refreshed license parameters, and the expiry extends immediately by one year. +4. If the client stays offline, export the new license manually and guide the customer through a local replacement. + +> **Tip**: After renewals or expansions, remind customers to trigger a “re-validate” action (restart service or run a refresh command) so the new policy applies. + +## FAQ and Best Practices + +- **Activation limit reached**: In “Customer Details → Activated Devices”, release inactive devices or raise the activation cap. +- **Heartbeat timeout**: Ensure the client can reach the License Manager API endpoint; allow the domain/port on gateways or proxies. +- **Fingerprint changes**: Use multi-factor fingerprints (MAC + CPU + HostID) and enable “fingerprint similarity” rules to avoid reissuing due to a single component swap. +- **Offline updates**: Prepare an “offline update bundle” with the license, client SDK, and config templates to minimize manual copy errors. + +Following these steps lets you deliver, monitor, and renew licenses efficiently across diverse customer environments—maximizing the value of License Manager’s lifecycle management capabilities. + diff --git a/docs/guide/operating_guide.md b/docs/guide/operating_guide.md new file mode 100644 index 0000000..56bde9e --- /dev/null +++ b/docs/guide/operating_guide.md @@ -0,0 +1,72 @@ +# 操作指南 + +## 使用背景 + +操作指南围绕 License Manager 的“创建授权 → 分发授权码 → 客户激活 → 心跳监控/续费”闭环展开。本文面向运营、售后与实施人员，帮助你快速把握不同部署模式（在线 / 离线 / 混合）的操作重点，并降低沟通成本。 + +## 术语回顾 + +- **授权码（License Code）**：在管理后台创建授权策略后生成的唯一标识码。它定义了有效期、最大激活设备数、可用功能模块、部署模式等信息。 +- **许可证（License File/Key）**：与具体设备硬件指纹绑定的加密文件，客户端在启动时使用许可证进行本地验证。 +- **硬件指纹（Hardware Fingerprint）**：客户端上报或人工采集的机器标识（例如 MAC、CPU 序列号、HostID），用于防止许可证被复制。 +- **心跳（Heartbeat）**：在线或混合模式下，客户端定期向服务端上报的状态数据，便于远程控制、续期与审计。 + +## 操作流程总览 + +```mermaid +graph TD + A[创建授权策略] --> B[生成授权码] + B --> C{部署模式?} + C -->|在线/混合| D[客户录入授权码
+自动激活] + C -->|离线| E[采集硬件指纹
生成许可证] + D --> F[心跳监控 & 远程控制] + E --> G[本地验证 & 手工更新] + F --> H[续费/扩容] + G --> H +``` + +1. **创建授权策略**：在后台录入客户信息、功能模块、有效期、部署模式与激活上限。 +2. **分发授权码/许可证**：根据部署模式将授权码或离线许可证交付客户。 +3. **客户激活**：客户端携带授权码 + 硬件指纹向服务端换取许可证，或直接加载离线许可证。 +4. **运行期管理**：通过心跳监控活跃状态，必要时下发禁用、续费、扩容等策略。 + +## 业务示例 + +### 示例 1：试用 7 天，客户部署100台服务器（在线模式） + +1. 创建授权码，设置有效期 7 天、最大激活数 2、部署类型选择“云端/在线”，启用试用功能集。 +2. 将授权码（例如 `LIC-2266-EtgAHCyh8HJT-hTAA`）发给客户，并说明需要放入产品指定目录或配置文件。 +3. 第一台服务器启动后，客户端读取授权码与本机硬件指纹，通过 REST API 请求管理平台，平台返回绑定该服务器的许可证。 +4. 管理后台可看到“激活进度 1/100”，并记录该设备的指纹与活跃时间。 +5. 第一百台服务器重复上述流程，激活进度更新为 100/100。此后若第一百零一台服务器尝试激活，将被拒绝。 +6. 7 天到期后，客户端本地验证失败，弹出续费提示，运营人员可在后台延长有效期或切换到付费功能集。 + +> **提示**：在线模式建议开启心跳告警，便于追踪试用期内的使用情况与潜在续费信号。 + +### 示例 2：离线部署，单台服务器永久授权 + +1. 创建授权码，设置有效期为“永久”，最大激活数 2，部署类型选择“离线”，启用合同约定的功能集。 +2. 通过脚本或 License Manager 提供的离线采集工具，获取客户服务器的硬件指纹，并让客户确认指纹采集准确。 +3. 在后台进入“离线许可证”流程，选择对应授权码并录入硬件指纹，生成许可证文件后下载。 +4. 将许可证交付客户，由其放入服务器指定位置（通常是配置目录或系统变量）。 +5. 客户产品启动时即可通过本地验证，后续若硬件变更，需要重新采集指纹并生成新许可证。 + +> **提示**：离线模式下无法自动感知设备变化，建议在合同中约定指纹变更流程，避免非授权转移。 + +### 示例 3：试用到期后续费 1 年（在线/混合模式通用） + +1. 在后台定位客户的试用授权，将有效期由“7 天”调整为“1 年”，必要时同时调整功能模块或激活上限。 +2. 保存后，系统会将授权状态标记为“待同步”，并在下一次心跳响应中返回“需要更新”的标记。 +3. 客户端检测到更新信号后，自动下载新的许可证或授权参数，过期时间即时延长 1 年。 +4. 若客户端长时间离线，可通过后台导出新的许可证，并指导客户手工替换。 + +> **提示**：续费或扩容后，务必通知客户触发一次“重新验证”动作（如重启服务或执行刷新命令），以确保新策略生效。 + +## 常见问题与最佳实践 + +- **激活数不足**：在“客户详情 → 激活设备”中检查占用情况，可手动释放失联设备或提高激活上限。 +- **心跳超时**：确认客户端可访问 License Manager 的 API 地址，必要时在网关或代理上放行相关域名与端口。 +- **硬件指纹变更**：建议使用多因子指纹（如 MAC+CPU+HostID），并在后台开启“指纹相似度”策略，避免因单一部件更换导致重新授权。 +- **离线环境更新**：建立“离线更新包”流程，包含许可证、客户端 SDK 及配置模板，减少人工拷贝错误。 + +通过以上流程与场景指引，可在不同客户环境下快速完成授权交付、监控与续费操作，充分发挥 License Manager 的全生命周期管理能力。 \ No newline at end of file