WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/.kiro/specs/license-system/requirements.md
WuYongJie ba98bf22cc feat: 添加许可证系统、Agent部署模块和Harbor镜像管理 
- 新增许可证服务器 (license-server/)
- 新增 Agent 部署模块 (flnxi-agent/)
- 添加许可证验证和激活页面
- 添加 Harbor 镜像同步脚本
- 更新素材系统支持许可证验证
2025-12-15 21:19:46 +08:00

15 KiB
Raw Blame History

Requirements Document

Introduction

本文档定义了 FLNXI 素材系统的许可证管理系统需求。该系统旨在实现软件的商业化分发，支持免费版、标准版和Pro版三个版本，通过联网验证和硬件指纹绑定实现防破解保护。系统包含两个主要部分：部署在客户端的许可证验证模块，以及部署在中央服务器的许可证验证服务和客户管理后台。

Glossary

  • License（许可证）: 授权客户使用软件特定版本和功能的凭证
  • License Key（许可证密钥）: 用于激活许可证的唯一字符串，格式为 XXXX-XXXX-XXXX-XXXX
  • Hardware Fingerprint（硬件指纹）: 基于客户服务器硬件特征生成的唯一标识符
  • License Server（许可证服务器）: 部署在 45.249.208.118 的中央验证服务
  • Client Instance（客户端实例）: 部署在客户 NAS/服务器上的 FLNXI 素材系统实例
  • Heartbeat（心跳）: 客户端定期向服务器发送的存活和验证请求
  • Grace Period（宽限期）: 网络断开后允许继续使用的时间窗口
  • Admin Portal（管理后台）: 用于管理客户和许可证的 Web 界面
  • Code Obfuscation（代码混淆）: 将源代码转换为难以阅读和理解的形式，增加逆向工程难度
  • Agent（安装代理）: 运行在客户 NAS 上的轻量级 Docker 容器，提供 Web 安装界面，帮助客户自助完成系统部署
  • Semantic Versioning（语义化版本）: 版本号格式为 v主版本.次版本.修订号（如 v1.2.3）
  • Rollback（回滚）: 将系统恢复到之前版本的操作
  • Forced Update（强制更新）: 必须完成才能继续使用系统的更新
  • Optional Update（可选更新）: 用户可自行决定是否执行的更新

Requirements

Requirement 1: 许可证版本定义

User Story: As a 系统管理员, I want to 定义不同版本的功能限制, so that 可以实现差异化的产品定价策略。

Acceptance Criteria

  1. THE License_Server SHALL support three license types: FREE, STANDARD, and PRO
  2. WHEN a license type is FREE, THE System SHALL enforce a maximum of 10 users
  3. WHEN a license type is FREE, THE System SHALL enforce a maximum of 100 materials
  4. WHEN a license type is FREE, THE System SHALL disable custom template functionality
  5. WHEN a license type is FREE, THE System SHALL disable advanced system settings
  6. WHEN a license type is FREE, THE System SHALL disable department isolation functionality
  7. WHEN a license type is STANDARD or PRO, THE System SHALL allow unlimited users and materials
  8. WHEN a license type is PRO, THE System SHALL enable intranet penetration functionality

Requirement 2: 许可证激活

User Story: As a 客户, I want to 使用许可证密钥激活系统, so that 可以解锁对应版本的功能。

Acceptance Criteria

  1. WHEN a user first accesses the system without activation, THE System SHALL display an activation page
  2. WHEN a user enters a valid license key, THE System SHALL send an activation request to the License_Server
  3. WHEN the License_Server receives an activation request, THE System SHALL validate the license key format and existence
  4. WHEN the license key is valid and not already activated, THE License_Server SHALL bind the license to the hardware fingerprint
  5. WHEN activation succeeds, THE Client_Instance SHALL store the license information locally
  6. WHEN a user chooses "free trial" without a license key, THE System SHALL activate as FREE version automatically
  7. IF the license key is invalid or already activated on another device, THEN THE System SHALL display an appropriate error message
  8. WHEN activation completes, THE System SHALL redirect to the main application

Requirement 3: 硬件指纹生成

User Story: As a 系统, I want to 生成稳定的硬件指纹, so that 许可证可以绑定到特定设备而不受常见硬件升级影响。

Acceptance Criteria

  1. THE System SHALL generate a hardware fingerprint using machine ID, hostname, and primary MAC address
  2. THE System SHALL NOT include RAM information in the hardware fingerprint
  3. THE System SHALL NOT include non-system disk information in the hardware fingerprint
  4. THE System SHALL generate a unique instance ID on first activation and store it persistently
  5. WHEN hardware components change, THE System SHALL use a weighted matching algorithm with a 60% threshold
  6. WHEN the fingerprint match score falls below 60%, THE System SHALL require re-activation

Requirement 4: 许可证验证

User Story: As a 系统, I want to 定期验证许可证状态, so that 可以确保只有合法用户使用付费功能。

Acceptance Criteria

  1. WHEN the system starts, THE Client_Instance SHALL verify the license with the License_Server
  2. WHILE the system is running, THE Client_Instance SHALL send heartbeat requests every hour
  3. WHEN the License_Server receives a verification request, THE System SHALL check license validity, expiration, and hardware fingerprint
  4. WHEN verification succeeds, THE License_Server SHALL return the current license configuration
  5. WHEN verification fails due to network issues, THE Client_Instance SHALL use cached license data
  6. WHEN the system operates offline, THE Client_Instance SHALL allow a grace period of 7 days
  7. IF the grace period expires without successful verification, THEN THE System SHALL enter read-only mode

Requirement 5: 功能限制执行

User Story: As a 系统, I want to 根据许可证类型限制功能, so that 免费用户无法使用付费功能。

Acceptance Criteria

  1. WHEN a FREE user attempts to create the 11th user, THE System SHALL block the operation and display an upgrade prompt
  2. WHEN a FREE user attempts to upload the 101st material, THE System SHALL block the operation and display an upgrade prompt
  3. WHEN a FREE user accesses custom template settings, THE System SHALL hide or disable the functionality
  4. WHEN a FREE user accesses department isolation settings, THE System SHALL hide or disable the functionality
  5. WHEN checking feature availability, THE System SHALL query the cached license configuration
  6. THE System SHALL display current usage statistics (users/materials count) in the settings page

Requirement 6: 客户管理后台

User Story: As a 平台管理员, I want to 管理所有客户的许可证, so that 可以进行销售和客户服务。

Acceptance Criteria

  1. THE Admin_Portal SHALL require authentication to access
  2. WHEN an admin views the dashboard, THE System SHALL display total customers count by license type
  3. WHEN an admin views the customer list, THE System SHALL display company name, license type, status, and expiration date
  4. WHEN an admin creates a new license, THE System SHALL generate a unique license key
  5. WHEN an admin upgrades a customer's license, THE System SHALL update the license type immediately
  6. WHEN an admin disables a license, THE System SHALL mark it as inactive and reject future verifications
  7. WHEN an admin resets hardware fingerprint, THE System SHALL allow the license to be activated on a new device
  8. THE Admin_Portal SHALL display usage statistics for each customer (user count, material count, last heartbeat)

Requirement 7: 异常检测

User Story: As a 平台管理员, I want to 检测许可证滥用行为, so that 可以防止盗版和许可证共享。

Acceptance Criteria

  1. WHEN the same license key sends heartbeats from multiple different hardware fingerprints within 24 hours, THE System SHALL flag it as suspicious
  2. WHEN suspicious activity is detected, THE Admin_Portal SHALL display an alert
  3. WHEN an admin reviews suspicious activity, THE System SHALL show the list of hardware fingerprints and their locations
  4. THE Admin_Portal SHALL allow admins to whitelist legitimate multi-device scenarios

Requirement 8: 许可证信息展示

User Story: As a 客户, I want to 查看当前许可证状态, so that 可以了解使用情况和到期时间。

Acceptance Criteria

  1. THE System SHALL display license information in the system settings page
  2. THE System SHALL show license type, activation status, expiration date, and feature availability
  3. THE System SHALL show current usage (user count, material count) compared to limits
  4. WHEN the license is about to expire within 30 days, THE System SHALL display a renewal reminder
  5. THE System SHALL provide a link to upgrade or renew the license

Requirement 9: 安全通信

User Story: As a 系统, I want to 确保许可证通信安全, so that 验证过程无法被篡改或伪造。

Acceptance Criteria

  1. THE System SHALL use HTTP with application-layer encryption for communication between Client_Instance and License_Server
  2. THE System SHALL encrypt request payloads using AES-256-GCM before transmission
  3. THE System SHALL sign all license data using RSA asymmetric encryption
  4. THE Client_Instance SHALL verify the signature of license data using the embedded public key
  5. THE System SHALL include timestamps in requests to prevent replay attacks
  6. IF signature verification fails, THEN THE System SHALL reject the license data and log the incident
  7. THE System SHALL support upgrading to HTTPS when SSL certificates are configured

Requirement 10: 数据持久化

User Story: As a 系统, I want to 安全存储许可证数据, so that 系统重启后无需重新激活。

Acceptance Criteria

  1. THE Client_Instance SHALL store license data in the database with encryption
  2. THE Client_Instance SHALL store the instance ID persistently across restarts
  3. THE License_Server SHALL store all customer and license data in a PostgreSQL database
  4. THE System SHALL backup license data regularly to prevent data loss
  5. WHEN license data is corrupted, THE System SHALL attempt to recover from the License_Server

Requirement 11: 代码混淆保护

User Story: As a 系统, I want to 对关键代码进行混淆处理, so that 增加逆向工程和破解的难度。

Acceptance Criteria

  1. THE Build_Process SHALL obfuscate license verification related source files during production build
  2. THE Build_Process SHALL obfuscate hardware fingerprint generation source files during production build
  3. THE Build_Process SHALL obfuscate cryptographic signature verification source files during production build
  4. THE Build_Process SHALL NOT obfuscate business logic components to maintain debuggability
  5. WHEN obfuscation is applied, THE System SHALL maintain identical functionality to non-obfuscated code
  6. THE Build_Process SHALL use control flow flattening and string encoding techniques
  7. THE Build_Process SHALL generate source maps separately for internal debugging purposes only
  8. WHEN the production build completes, THE System SHALL verify that obfuscated code executes correctly

Requirement 12: 自助安装（Agent 方案）

User Story: As a 客户, I want to 通过简单的方式自助部署和更新系统, so that 无需手动配置 Docker 命令，也不需要联系技术支持。

Acceptance Criteria

  1. THE System SHALL provide a lightweight Agent Docker image (flnxi/flnxi-agent) on Docker Hub for customers to download
  2. THE Agent image SHALL be compatible with mainstream NAS systems including Synology, QNAP, and fnOS
  3. WHEN the Agent container starts, THE Agent SHALL provide a Web-based management interface on port 9000
  4. THE Agent Web interface SHALL allow customer to configure system port (default 4320)
  5. THE Agent SHALL NOT perform license validation (license activation is handled by the material system on first startup)
  6. WHEN customer clicks install, THE Agent SHALL pull the FLNXI material system image from harbor.flnxi.com/flnxi/material/flnxi-material
  7. THE Agent SHALL create and start the FLNXI material system container with configured settings
  8. THE Agent Web interface SHALL display installation progress with clear status messages
  9. WHEN installation completes, THE Agent SHALL display the access URL for the system
  10. IF installation fails, THEN THE Agent SHALL display error details and provide retry option
  11. THE Agent SHALL provide system update functionality to pull and deploy latest version
  12. THE Agent Web interface SHALL display current system version and available updates
  13. THE Agent SHALL NOT collect or transmit any customer usage data
  14. THE Agent container SHOULD be kept running for future system updates

Requirement 13: 版本管理

User Story: As a 平台管理员, I want to 管理系统版本发布, so that 可以有序地向客户推送更新。

Acceptance Criteria

  1. THE System SHALL use semantic versioning format (vMAJOR.MINOR.PATCH) for all releases
  2. THE License_Server SHALL maintain version information including latest version and minimum required version
  3. WHEN a new version is released, THE Admin_Portal SHALL allow setting the minimum required version
  4. THE License_Server SHALL provide a version check API that returns latest version, minimum required version, and release notes
  5. THE System SHALL store version number in /app/VERSION.txt within the Docker image
  6. THE Harbor registry SHALL retain at least the 3 most recent versions for rollback purposes

Requirement 14: 系统更新

User Story: As a 客户, I want to 方便地更新系统到最新版本, so that 可以获得新功能和安全修复。

Acceptance Criteria

  1. WHEN the Agent checks for updates, THE Agent SHALL compare current version with latest version from License_Server
  2. WHEN an optional update is available, THE Agent SHALL display update notification with version number and release notes
  3. WHEN a forced update is required, THE System SHALL block access to main application until update is completed
  4. WHEN customer initiates update, THE Agent SHALL pull new image using Docker incremental layer download
  5. THE Agent SHALL display download progress and estimated time during update
  6. WHEN update completes, THE Agent SHALL restart the system container automatically
  7. IF update fails, THEN THE Agent SHALL automatically rollback to previous version
  8. THE Agent Web interface SHALL provide manual rollback option to any of the 3 most recent versions

Requirement 15: 更新回滚机制

User Story: As a 客户, I want to 在更新失败时自动恢复, so that 系统不会因为更新问题而无法使用。

Acceptance Criteria

  1. WHEN starting an update, THE Agent SHALL backup current container configuration
  2. WHEN starting an update, THE Agent SHALL rename current container instead of deleting it
  3. WHEN new container starts, THE Agent SHALL perform health check by calling /api/health endpoint
  4. WHEN health check fails within 60 seconds, THE Agent SHALL trigger automatic rollback
  5. WHEN rollback is triggered, THE Agent SHALL stop new container, restore backup container, and restart it
  6. WHEN rollback completes, THE Agent SHALL display message indicating rollback reason and restored version
  7. THE Agent Web interface SHALL allow manual rollback with version selection