📝 docs: Add documentation

docs/zh/admin/maintenance/nodes.md

@@ -0,0 +1,187 @@
+# 节点管理
+
+管理面向用户的代理节点,配置节点与服务器的关联、入口地址和标签。节点是用户实际连接的端点,一个服务器可以对应多个节点。
+
+## 页面组成
+
+### 节点列表
+
+以表格形式展示所有节点的配置信息。
+
+**列信息:**
+- **启用状态 (Enabled)**: 开关按钮,实时控制节点是否对用户可见
+  - 开启: 节点在订阅中显示,用户可连接
+  - 关闭: 节点隐藏,用户无法连接
+  - 即时生效,无需重启
+- **名称 (Name)**: 节点显示名称,会展示在用户的客户端中
+- **地址:端口 (Address:Port)**: 用户连接的入口地址和端口
+- **服务器 (Server)**: 显示关联的服务器名称和 IP 地址
+  - 格式: `服务器名称:服务器IP`
+- **协议:端口 (Protocol:Port)**: 使用的代理协议类型及服务器监听端口
+  - 格式: `协议类型:服务器端口`
+  - 示例: `vless:443`, `vmess:80`, `trojan:8443`
+- **标签 (Tags)**: 节点分组标签,以徽章形式显示
+  - 用于权限分组和套餐绑定
+  - 用于流量分发策略
+  - 支持多个标签
+
+**操作功能:**
+- **搜索**: 根据关键词快速筛选节点
+- **排序**: 通过拖拽行调整节点显示顺序,影响用户订阅中的节点排序
+- **分页**: 支持大量节点的分页浏览
+- **批量删除**: 选中多个节点后批量删除
+
+**单个节点操作:**
+- **编辑 (Edit)**: 修改节点配置
+- **删除 (Delete)**: 删除节点
+- **复制 (Copy)**: 复制节点配置创建新节点(新节点默认禁用)
+
+## 节点表单
+
+点击"创建 (Create)"或"编辑 (Edit)"时打开的侧边栏表单。
+
+### 表单字段
+
+**1. 服务器 (Server)** - 必填
+- 选择节点关联的物理服务器
+- 下拉列表显示: `服务器名称 (服务器IP)`
+- 选择后自动触发智能填充
+
+**2. 协议 (Protocol)** - 必填
+- 选择使用的代理协议
+- 下拉列表仅显示所选服务器已启用的协议
+- 格式: `协议类型 (端口号)`
+- 支持的协议: shadowsocks, vmess, vless, trojan, hysteria, tuic, anytls, naive, http, socks, mieru
+- 选择后自动填充对应端口
+
+**3. 名称 (Name)** - 必填
+- 节点的显示名称
+- 会展示在用户的代理客户端中
+- 支持自动填充(从服务器名称)
+
+**4. 地址 (Address)** - 必填
+- 用户连接的入口地址
+- 可以是域名或 IP 地址
+- 支持自动填充(从服务器地址)
+- 可手动修改为 CDN 域名或其他入口
+
+**5. 端口 (Port)** - 必填
+- 用户连接的入口端口号
+- 范围: 1-65535
+- 支持自动填充(从协议端口)
+- 可手动修改为不同端口(如使用端口转发时)
+
+**6. 标签 (Tags)** - 可选
+- 节点分组标签,支持多标签
+- 可从已有标签中选择或输入新标签
+- 使用回车键或逗号(,)添加多个标签
+- 作用:
+  - **权限分组**: 与套餐绑定,控制不同套餐用户可见的节点
+  - **流量策略**: 用于节点流量分发和负载均衡
+
+### 智能填充机制
+
+表单具有智能填充功能,提高配置效率:
+
+**触发条件:**
+1. 选择服务器时
+2. 选择协议时
+
+**填充规则:**
+- **选择服务器后**:
+  - 名称自动填充为服务器名称
+  - 地址自动填充为服务器 IP
+  - 协议自动选择第一个可用协议
+  - 端口自动填充为协议对应端口
+
+- **选择协议后**:
+  - 端口自动填充为该协议的端口号
+
+**手动修改:**
+- 任何字段手动修改后,该字段不再自动填充
+- 重新选择服务器或协议会刷新自动填充状态
+
+## 使用场景
+
+### 场景 1: 创建基础节点
+1. 点击"创建 (Create)"按钮
+2. 选择服务器(自动填充其他字段)
+3. 确认或调整自动填充的配置
+4. 点击"确认 (Confirm)"
+
+### 场景 2: 创建 CDN 节点
+1. 点击"创建 (Create)"按钮
+2. 选择服务器
+3. 修改名称为: `香港 01 [CDN]`
+4. 修改地址为 CDN 域名: `hk01.cdn.example.com`
+5. 修改端口为 CDN 端口: `443` 或 `80`
+6. 点击"确认 (Confirm)"
+
+### 场景 3: 标签分组管理
+**用于套餐绑定:**
+- 高级套餐节点: 添加标签 `premium`, `vip`
+- 普通套餐节点: 添加标签 `standard`
+- 试用套餐节点: 添加标签 `trial`
+- 在产品管理中绑定标签,实现不同套餐看到不同节点
+
+**用于地区分类:**
+- 香港节点: 添加标签 `hk`, `asia`
+- 美国节点: 添加标签 `us`, `americas`
+- 日本节点: 添加标签 `jp`, `asia`
+
+### 场景 4: 批量管理
+1. 使用搜索功能筛选特定节点
+2. 勾选多个节点
+3. 点击批量删除或批量操作
+4. 确认操作
+
+## 节点与服务器的关系
+
+**服务器 (Server):**
+- 物理服务器或 VPS
+- 运行代理服务程序
+- 配置监听协议和端口
+- 一台服务器可配置多种协议
+
+**节点 (Node):**
+- 用户可见的连接端点
+- 关联到某台服务器的某个协议
+- 配置用户连接的入口地址(可与服务器地址不同)
+- 一台服务器可创建多个节点
+
+**示例:**
+```
+服务器: 香港-HK01 (192.168.1.100)
+├── 协议: vless:443
+├── 协议: vmess:80
+└── 协议: trojan:8443
+
+节点配置:
+1. 节点名称: 香港 01 [直连]
+   - 服务器: 香港-HK01
+   - 协议: vless:443
+   - 地址: 192.168.1.100
+   - 端口: 443
+
+2. 节点名称: 香港 01 [CDN]
+   - 服务器: 香港-HK01
+   - 协议: vmess:80
+   - 地址: hk01.cdn.example.com
+   - 端口: 443 (CDN端口)
+
+3. 节点名称: 香港 01 [VIP]
+   - 服务器: 香港-HK01
+   - 协议: trojan:8443
+   - 地址: 192.168.1.100
+   - 端口: 8443
+   - 标签: premium, vip
+```
+
+## 注意事项
+
+1. **协议必须已启用**: 只能选择服务器上已启用的协议,未启用的协议不会出现在下拉列表中
+2. **删除影响**: 删除节点会导致使用该节点的用户无法连接,请谨慎操作
+3. **禁用vs删除**: 临时下线节点建议使用"禁用"而非删除,方便后续恢复
+4. **标签规划**: 建议提前规划标签体系,便于后续套餐和节点的批量管理
+5. **地址配置**: 使用 CDN 时,确保 CDN 已正确配置回源到服务器地址
+6. **端口映射**: 如果入口端口与服务器监听端口不同(如使用端口转发),需确保网络层面已配置正确

docs/zh/admin/maintenance/products.md

@@ -0,0 +1,261 @@
+# 产品管理
+
+产品管理模块用于创建和管理各类订阅套餐产品,是商业运营的核心模块。
+
+## 功能概述
+
+### 产品列表
+
+查看和管理所有产品套餐:
+
+- **产品名称**: 套餐的显示名称
+- **产品类型**: 周期套餐/流量包/按量计费
+- **价格**: 产品售价和优惠价
+- **流量配额**: 总流量/每月流量
+- **有效期**: 套餐时长(月/季/年)
+- **节点组**: 包含的节点组
+- **状态**: 上架/下架/售罄
+- **销量**: 产品销售数量
+
+### 创建产品
+
+创建新的订阅套餐:
+
+#### 基本信息
+
+- **产品名称**: 用户看到的套餐名称
+- **产品描述**: 详细的产品说明
+- **产品分类**: 基础版/进阶版/旗舰版
+- **排序**: 产品显示顺序
+
+#### 价格设置
+
+- **原价**: 产品原始价格
+- **售价**: 实际销售价格
+- **优惠**: 折扣百分比
+- **货币**: 人民币/美元等
+- **支付周期**: 月付/季付/年付
+
+#### 流量配置
+
+- **总流量**: 套餐总流量配额
+- **流量周期**: 一次性/每月重置
+- **流量倍率**: 流量计费倍率
+- **流量超额**: 超额后的处理方式
+
+#### 时长设置
+
+- **有效期**: 套餐使用期限
+- **计费周期**: 按月/按季/按年
+- **自动续费**: 是否支持自动续费
+- **续费优惠**: 续费时的折扣
+
+#### 节点配置
+
+- **包含节点组**: 选择套餐包含的节点组
+- **节点限制**: 同时连接设备数限制
+- **速度限制**: 单用户速度上限
+- **可用地区**: 限制使用地区
+
+#### 高级选项
+
+- **库存管理**: 设置产品库存数量
+- **购买限制**: 每人限购数量
+- **新用户专享**: 仅新用户可购买
+- **试用设置**: 提供免费试用
+
+### 编辑产品
+
+修改现有产品的配置:
+
+- 调整价格和优惠
+- 更新流量配额
+- 修改节点范围
+- 变更产品状态
+
+::: warning 注意
+修改产品配置不会影响已购买的用户,只对新订单生效。
+:::
+
+### 删除产品
+
+删除产品前需确认:
+
+- 是否有用户正在使用
+- 是否有未完成的订单
+- 是否要保留历史数据
+
+建议先下架产品,确认无问题后再删除。
+
+## 产品分类
+
+### 按周期分类
+
+#### 月付套餐
+
+- 灵活性高,适合短期用户
+- 价格相对较高
+- 方便用户尝试服务
+
+#### 季付套餐
+
+- 适中的价格和使用期
+- 平衡灵活性和优惠
+- 适合大多数用户
+
+#### 年付套餐
+
+- 价格优惠幅度大
+- 适合长期用户
+- 降低用户流失率
+
+#### 终身套餐
+
+- 一次性付费永久使用
+- 价格较高但性价比高
+- 适合忠实用户
+
+### 按流量分类
+
+#### 流量包
+
+- 固定流量额度
+- 用完即止
+- 适合流量需求明确的用户
+
+#### 不限流量
+
+- 无流量限制
+- 可能限制速度
+- 适合重度用户
+
+#### 按量计费
+
+- 用多少付多少
+- 灵活但成本可能高
+- 适合偶尔使用的用户
+
+### 按等级分类
+
+#### 基础版
+
+- 价格实惠
+- 基础节点组
+- 适合轻度使用
+
+#### 进阶版
+
+- 性价比高
+- 更多节点选择
+- 适合日常使用
+
+#### 旗舰版
+
+- 全部节点访问
+- 最高速度和稳定性
+- 适合专业用户
+
+## 产品定价策略
+
+### 定价原则
+
+- **成本导向**: 覆盖服务器和带宽成本
+- **竞争导向**: 参考同行业定价
+- **价值导向**: 根据提供的价值定价
+- **心理定价**: 利用价格心理学
+
+### 促销策略
+
+#### 限时优惠
+
+- 节假日促销
+- 周年庆活动
+- 新品上市优惠
+
+#### 优惠券
+
+- 满减优惠券
+- 折扣优惠券
+- 新用户优惠券
+
+#### 会员折扣
+
+- VIP 用户专享折扣
+- 累计消费返利
+- 推荐奖励
+
+#### 组合套餐
+
+- 多产品组合优惠
+- 套餐升级优惠
+- 续费优惠
+
+## 产品展示
+
+### 产品页面
+
+优化产品展示提高转化率:
+
+- **清晰的标题**: 突出产品特点
+- **详细的描述**: 说明产品优势
+- **价格对比**: 展示优惠力度
+- **用户评价**: 展示真实反馈
+- **购买引导**: 明确的购买按钮
+
+### 产品对比
+
+帮助用户选择合适的套餐:
+
+- **对比表格**: 多个套餐并排对比
+- **推荐标签**: 标注热门或推荐套餐
+- **差异化**: 突出不同套餐的区别
+- **适用场景**: 说明适合的使用场景
+
+## 产品分析
+
+### 销售数据
+
+分析产品销售情况:
+
+- **销量统计**: 各产品销售数量
+- **收入统计**: 各产品产生的收入
+- **转化率**: 访问到购买的转化
+- **用户画像**: 购买用户特征
+
+### 产品优化
+
+根据数据优化产品:
+
+- **价格调整**: 优化定价策略
+- **配置优化**: 调整流量和节点
+- **促销优化**: 改进促销方案
+- **体验优化**: 提升购买流程
+
+## 库存管理
+
+### 库存设置
+
+- **库存数量**: 设置产品库存
+- **库存预警**: 低库存提醒
+- **补货策略**: 自动补货规则
+
+### 库存监控
+
+- **实时库存**: 查看当前库存
+- **库存流水**: 库存变动记录
+- **销售预测**: 预测库存需求
+
+## 最佳实践
+
+- 提供多种价格档位满足不同需求
+- 设置明确的产品特点和优势
+- 定期分析销售数据优化产品
+- 保持产品信息的及时更新
+- 合理使用促销提高销量
+- 收集用户反馈持续改进
+
+## 下一步
+
+- [订单管理](/zh/admin/commerce/orders) - 处理产品订单
+- [优惠券管理](/zh/admin/commerce/coupons) - 创建优惠活动
+- [营销管理](/zh/admin/commerce/marketing) - 推广产品

docs/zh/admin/maintenance/servers.md

@@ -0,0 +1,214 @@
+# 服务器管理
+
+管理代理服务器的基础信息、协议配置和运行状态,并配置全局节点参数。
+
+## 页面组成
+
+服务器管理页面包含以下模块:
+
+### 1. 动态倍率配置
+
+位于页面顶部的卡片,用于定义不同时段的流量计费倍率。
+
+**功能特性:**
+- **时段管理**: 定义多个时间段,每个时段包含:
+  - 开始时间 (Start time): 格式为 HH:MM:SS
+  - 结束时间 (End time): 格式为 HH:MM:SS
+  - 倍率 (Multiplier): 该时段的流量计费倍数
+- **动态计费**: 在不同时间段应用不同倍率,如高峰时段可设置更高倍率
+- **灵活配置**: 支持添加、编辑、删除时间段
+- **立即生效**: 保存后实时应用于流量统计
+
+**使用场景:**
+- 高峰/低峰分时计费
+- 节假日特殊计费
+- 限制高峰时段流量使用
+
+### 2. 节点配置
+
+位于页面顶部的卡片,配置节点通信和全局策略。
+
+**基础配置 (Basic Configuration):**
+- **节点密钥 (Node Secret)**: 节点与服务器通信的认证密钥
+- **节点拉取间隔 (Node Pull Interval)**: 节点从服务器拉取配置的时间间隔(秒)
+- **节点推送间隔 (Node Push Interval)**: 节点向服务器推送状态的时间间隔(秒)
+- **流量报告阈值 (Traffic Report Threshold)**: 触发流量报告的字节数阈值
+- **IP 策略 (IP Strategy)**: 选择 prefer_ipv4 或 prefer_ipv6
+
+**DNS 配置 (DNS Configuration):**
+- **协议 (Protocol)**: tcp, udp, tls, https, quic
+- **地址 (Address)**: DNS 服务器地址
+- **域名 (Domains)**: 使用该 DNS 解析的域名列表
+- 支持配置多个 DNS 服务器
+
+**出站规则 (Outbound Rules):**
+为特定流量配置出站代理:
+- **名称 (Name)**: 规则标识
+- **协议 (Protocol)**: 代理协议类型
+- **地址 (Address)**: 代理服务器地址
+- **端口 (Port)**: 代理服务器端口
+- **加密方式 (Cipher)**: Shadowsocks 等协议的加密方法
+- **密码 (Password)**: 代理认证密码
+- **规则列表 (Rules)**: 匹配规则,如域名或 IP 范围
+
+**屏蔽规则 (Block Rules):**
+配置需要阻止的域名或 IP 列表,支持通配符和正则表达式。
+
+### 3. 服务器列表
+
+页面主体部分,以表格形式展示所有服务器。
+
+**列信息:**
+- **ID**: 服务器唯一标识,以徽章形式显示
+- **名称 (Name)**: 服务器自定义名称
+- **地址 (Address)**: 显示国家/城市/IP 地址,使用徽章组件
+- **协议 (Protocols)**: 显示已启用的协议列表,每个协议显示:
+  - 倍率 (如 1.00x)
+  - 协议类型 (如 vless, vmess, trojan, shadowsocks)
+  - 端口号
+- **状态 (Status)**: 在线/离线状态,带圆点指示器
+  - 绿色圆点: 在线
+  - 灰色圆点: 离线
+- **CPU**: CPU 使用率百分比,以进度条形式显示
+- **内存 (Memory)**: 内存使用率百分比,以进度条形式显示
+- **磁盘 (Disk)**: 磁盘使用率百分比,以进度条形式显示
+- **在线用户 (Online Users)**: 当前连接用户数
+
+**操作功能:**
+- **搜索**: 根据关键词快速筛选服务器
+- **排序**: 通过拖拽行调整服务器显示顺序,排序会保存到数据库
+- **分页**: 支持大量服务器的分页浏览
+- **批量删除**: 选中多个服务器后批量删除(已被节点引用的服务器不可删除)
+
+**单个服务器操作:**
+- **编辑 (Edit)**: 修改服务器配置
+- **连接 (Connect)**: 显示一键安装脚本
+- **删除 (Delete)**: 删除服务器(已被节点引用时禁用)
+- **复制 (Copy)**: 复制服务器配置创建新服务器
+
+## 服务器表单
+
+点击"创建 (Create)"或"编辑 (Edit)"时打开的侧边栏表单。
+
+**基础信息:**
+- **名称 (Name)**: 必填,服务器标识名称
+- **国家 (Country)**: 服务器所在国家代码(如 CN, US, JP)
+- **城市 (City)**: 服务器所在城市
+- **地址 (Address)**: 服务器 IP 地址或域名
+
+**协议配置:**
+
+支持配置多种代理协议,每种协议以手风琴形式展开配置。已在节点中使用的协议类型无法禁用。
+
+**常见协议字段:**
+- **启用 (Enable)**: 开关按钮,控制是否启用该协议
+- **端口 (Port)**: 监听端口号
+- **倍率 (Ratio)**: 流量计费倍数,如 1.5 表示实际流量的 1.5 倍
+- **加密/安全性**: 根据协议类型不同而不同
+
+**支持的协议类型:**
+
+1. **Shadowsocks**
+   - Cipher: 加密方法(如 aes-256-gcm, chacha20-poly1305)
+   - Password: 认证密码,支持生成随机密码
+
+2. **Trojan**
+   - Password: 认证密码,支持生成随机密码
+
+3. **Vmess**
+   - UUID: 用户标识,支持自动生成
+   - Alter ID: 额外 ID 数量
+
+4. **Vless**
+   - UUID: 用户标识,支持自动生成
+   - Flow: 流控模式(如 xtls-rprx-vision)
+
+5. **Hysteria**
+   - Up/Down Speed: 上传/下载速度限制
+   - Obfs Password: 混淆密码
+
+6. **Hysteria2**
+   - Password: 认证密码
+   - Obfs Password: 混淆密码
+
+7. **TUIC**
+   - UUID: 用户标识
+   - Password: 认证密码
+   - Congestion Control: 拥塞控制算法(如 bbr, cubic)
+   - UDP Relay Mode: UDP 中继模式
+
+**传输层配置 (Transport):**
+
+每个协议可配置不同的传输层:
+- **TCP**: 基础 TCP 传输
+- **WS (WebSocket)**: WebSocket 传输
+  - Path: WebSocket 路径
+  - Host: WebSocket Host 头
+- **gRPC**: gRPC 传输
+  - Service Name: gRPC 服务名
+- **HTTP/2**: HTTP/2 传输
+  - Path: 请求路径
+  - Host: Host 头
+- **QUIC**: QUIC 协议传输
+- **HTTPUpgrade**: HTTP 升级传输
+- **SplitHTTP**: 分离 HTTP 传输
+- **XHTTP**: 扩展 HTTP 传输
+
+**TLS 配置:**
+- **TLS**: 是否启用 TLS
+- **Server Name**: SNI 服务器名称
+- **ALPN**: 应用层协议协商(如 h2, http/1.1)
+- **Fingerprint**: TLS 指纹(如 chrome, firefox, safari)
+- **Reality**: Reality 协议配置
+  - Public Key: 公钥
+  - Short ID: 短 ID
+  - Spider X: Spider X 参数
+
+**高级配置:**
+- **Multiplex**: 多路复用设置
+- **Encryption**: 额外加密层
+- **Flow Control**: 流量控制参数
+
+**字段生成功能:**
+
+部分字段支持自动生成,带有钥匙图标:
+- **UUID**: 生成随机 UUID
+- **密码**: 生成随机强密码
+- **Reality 密钥对**: 生成 Public Key 和 Private Key
+- **Short ID**: 生成随机短 ID
+
+## 一键安装
+
+点击"连接 (Connect)"按钮显示服务器节点的安装脚本。
+
+**配置项:**
+- **API Host**: 管理面板的 API 地址(自动从当前域名获取,可手动修改)
+- **Server ID**: 当前服务器的唯一 ID(自动填充)
+- **Secret Key**: 从节点配置中自动获取
+
+**安装命令:**
+生成的 bash 脚本包含:
+```bash
+wget -N https://raw.githubusercontent.com/perfect-panel/ppanel-node/master/scripts/install.sh && bash install.sh --api-host [域名] --server-id [ID] --secret-key [密钥]
+```
+
+**操作:**
+- 点击"复制并关闭 (Copy and Close)"一键复制脚本并关闭弹窗
+- 在服务器上执行该脚本即可自动安装并连接节点
+
+## 在线用户查看
+
+点击"在线用户 (Online Users)"数字可查看当前服务器的在线用户详情。
+
+**显示信息:**
+- **用户账号**: 链接到用户详情页
+- **订阅 ID**: 订阅记录 ID
+- **订阅名称**: 所用套餐名称
+- **流量使用**: 已用流量 / 总流量(若无限制显示"Unlimited")
+- **到期时间**: 订阅过期时间,已过期显示红色"Expired"徽章
+- **IP 地址**: 用户连接 IP,可点击查看 IP 信息
+- **连接时间**: 用户建立连接的时间
+
+## 数据刷新
+
+服务器状态(CPU、内存、磁盘、在线用户)根据"节点配置"中设置的"节点推送间隔"实时更新。

docs/zh/admin/maintenance/subscribe-variables.md

@@ -0,0 +1,59 @@
+# 模板变量参考
+
+## 节点对象 (Proxy) 字段
+
+### 基础字段
+- `Name` - 节点名称
+- `Server` - 服务器地址
+- `Port` - 服务器端口
+- `Type` - 协议类型
+- `Tags` - 标签数组
+- `Sort` - 排序序号
+
+### 安全选项
+- `Security` - 安全协议
+- `SNI` - TLS 服务器名称
+- `AllowInsecure` - 是否允许不安全连接
+- `Fingerprint` - 客户端指纹
+- `RealityServerAddr` - Reality 服务器地址
+- `RealityPublicKey` - Reality 公钥
+- `RealityShortId` - Reality 短ID
+
+### 传输选项
+- `Transport` - 传输协议,如 ws、http、grpc
+- `Host` - WebSocket/HTTP 的 Host
+- `Path` - HTTP/HTTPS 路径
+- `ServiceName` - gRPC 服务名
+
+### 协议特定字段
+
+#### Shadowsocks
+- `Method` - 加密方法
+- `Cipher` - 加密算法
+- `ServerKey` - 服务器密钥
+
+#### Vmess/Vless
+- `UUID` - 用户ID
+- `Flow` - 流控模式
+- `Encryption` - 加密方式
+
+#### Trojan
+- `Password` - 密码
+
+#### Hysteria2
+- `UpMbps` - 上行带宽
+- `DownMbps` - 下行带宽
+- `ObfsPassword` - 混淆密码
+
+#### TUIC
+- `CongestionController` - 拥塞控制算法
+- `UDPRelayMode` - UDP 中继模式
+
+## 用户信息 (UserInfo) 字段
+
+- `Password` - 用户密码
+- `ExpiredAt` - 过期时间
+- `Download` - 已下载流量
+- `Upload` - 已上传流量
+- `Traffic` - 总流量
+- `SubscribeURL` - 订阅链接

docs/zh/admin/maintenance/subscribe.md

@@ -0,0 +1,284 @@
+<div v-pre>
+
+# 订阅配置
+
+配置订阅系统的全局设置和管理客户端应用的订阅模板。订阅配置决定用户如何获取和使用代理节点信息。
+
+## 页面组成
+
+订阅配置页面分为两大模块:
+
+### 1. 订阅配置 (Subscription Configuration)
+
+位于页面顶部的卡片,配置订阅系统的全局设置。
+
+**配置选项:**
+
+**单订阅模式 (Single Subscription Mode)**
+- 类型: 开关
+- 功能: 限制用户只能拥有一个激活的订阅
+- 说明: 不影响已存在的订阅,仅对新订阅生效
+- 使用场景: 控制订阅数量,防止账号共享
+
+**泛域名解析 (Wildcard Resolution)**
+- 类型: 开关
+- 功能: 启用订阅的泛域名解析
+- 说明: 允许使用通配符域名访问订阅链接
+- 示例: `*.example.com` 可匹配 `sub1.example.com`, `sub2.example.com`
+
+**订阅路径 (Subscription Path)**
+- 类型: 文本输入
+- 功能: 自定义订阅端点的 URL 路径
+- 格式: `/your-custom-path`
+- 说明: 系统重启后性能更佳
+- 示例: `/api/v1/subscribe` 或 `/sub`
+
+**订阅域名 (Subscription Domain)**
+- 类型: 多行文本
+- 功能: 自定义订阅链接的域名
+- 格式: 每行一个域名
+- 示例:
+  ```
+  example.com
+  www.example.com
+  sub.example.com
+  ```
+- 使用场景:
+  - 使用 CDN 域名
+  - 多域名负载均衡
+  - 域名备份
+
+**User-Agent 限制**
+- 类型: 开关
+- 功能: 启用基于 User-Agent 的访问控制
+- 说明: 只允许白名单中的客户端访问订阅
+- 使用场景: 防止爬虫、限制非法访问
+
+**User-Agent 白名单**
+- 类型: 多行文本
+- 功能: 配置允许访问订阅的 User-Agent 列表
+- 格式: 每行一个 User-Agent
+- 示例:
+  ```
+  ClashX
+  ClashForAndroid
+  Clash-verge
+  ```
+- 说明: 已配置的应用 User-Agent 会自动包含在内
+
+### 2. 客户端管理 (Client Management)
+
+管理不同代理客户端的订阅模板和下载链接。
+
+**表格列信息:**
+- **默认 (Default)**: 开关按钮,设置为默认客户端
+  - 默认客户端在订阅页面优先显示
+  - 同时只能有一个默认客户端
+- **客户端名称 (Client Name)**: 显示客户端图标和名称
+- **User-Agent**: 客户端标识符,用于识别不同客户端
+- **输出格式 (Output Format)**: 订阅内容的格式类型
+  - Base64: Base64 编码格式
+  - YAML: YAML 配置文件格式
+  - JSON: JSON 数据格式
+  - CONF: 配置文件格式
+  - Plain Text: 纯文本格式
+- **支持平台 (Supported Platforms)**: 显示该客户端支持的操作系统
+  - Windows, macOS, Linux, iOS, Android, HarmonyOS
+- **描述 (Description)**: 客户端详细说明
+
+**操作功能:**
+- **预览 (Preview)**: 查看生成的订阅模板内容
+  - Base64 格式显示原始内容和解码内容
+  - 其他格式直接显示内容
+  - 支持语法高亮
+- **编辑 (Edit)**: 修改客户端配置
+- **删除 (Delete)**: 删除客户端配置
+- **批量删除**: 选中多个客户端后批量删除
+
+**顶部工具栏:**
+- **Template Repo 链接**: 跳转到 GitHub 模板仓库
+  - 地址: https://github.com/perfect-panel/subscription-template
+  - 提供订阅模板示例和文档
+- **添加 (Add)**: 创建新的客户端配置
+
+## 客户端表单
+
+点击"添加 (Add)"或"编辑 (Edit)"时打开的侧边栏表单,分为三个标签页。
+
+### 基本信息 (Basic Info)
+
+**图标 (Icon)**
+- 类型: URL 输入 + 上传按钮
+- 格式: 图片 URL 或 Base64 编码
+- 示例: `https://example.com/icon.png`
+- 功能: 支持直接上传图片,自动转换为 Base64
+
+**名称 (Name)** - 必填
+- 类型: 文本输入
+- 功能: 客户端显示名称
+- 示例: `Clash for Windows`, `V2rayN`
+
+**User-Agent** - 必填
+- 类型: 文本输入
+- 功能: 客户端标识符,用于区分不同客户端
+- 示例: `Clash`, `V2rayN`, `ClashX`
+- 重要: 必须与客户端实际发送的 User-Agent 匹配
+
+**描述 (Description)** - 可选
+- 类型: 多行文本
+- 功能: 客户端详细说明
+- 内容: 客户端特性、使用说明等
+
+### 模板 (Templates)
+
+**输出格式 (Output Format)** - 必填
+- 类型: 下拉选择
+- 选项:
+  - **Base64**: 传统订阅格式,适用于大多数客户端
+  - **YAML**: Clash 系列客户端配置格式
+  - **JSON**: JSON 格式配置,适用于支持 JSON 的客户端
+  - **CONF**: 配置文件格式,如 Shadowrocket
+  - **Plain Text**: 纯文本格式
+
+**Scheme** - 可选
+- 类型: 文本输入
+- 功能: 自定义 URL Scheme
+- 示例: `clash://`, `vmess://`
+- 用途: 一键导入订阅
+
+**模板 (Template)** - 必填
+- 类型: Go Template 编辑器
+- 功能: 使用 Go 模板语法编写订阅内容
+- 支持: 语法高亮、代码补全
+- 变量:
+  - `{{.SiteName}}`: 网站名称
+  - `{{.SubscribeName}}`: 订阅名称
+  - `{{.Proxies}}`: 节点数组
+  - `{{.UserInfo}}`: 用户信息
+
+**模板变量说明**
+
+详细的模板变量参考请查看：[模板变量参考](./subscribe-variables.md)
+
+用户信息 (UserInfo) 字段：
+
+- `Password` - 用户密码
+- `ExpiredAt` - 过期时间
+- `Download` - 已下载流量
+- `Upload` - 已上传流量
+- `Traffic` - 总流量
+- `SubscribeURL` - 订阅链接
+
+### 下载链接 (Downloads)
+
+配置客户端的下载地址,支持多平台:
+
+- **Windows**: Windows 平台下载链接
+- **macOS**: macOS 平台下载链接
+- **Linux**: Linux 平台下载链接
+- **iOS**: iOS 平台下载链接
+- **Android**: Android 平台下载链接
+- **HarmonyOS**: 鸿蒙系统下载链接
+
+每个平台都是可选的,填写后会在客户端列表中显示对应的平台徽章。
+
+## 使用场景
+
+### 场景 1: 配置 Clash 客户端
+
+1. 点击"添加 (Add)"
+2. 基本信息:
+   - 名称: `Clash for Windows`
+   - User-Agent: `Clash`
+   - 图标: 上传 Clash 图标
+3. 模板:
+   - 输出格式: 选择 `YAML`
+   - 模板: 编写 Clash YAML 配置模板
+4. 下载链接:
+   - Windows: `https://github.com/Fndroid/clash_for_windows_pkg/releases`
+   - macOS: `https://github.com/yichengchen/clashX/releases`
+5. 点击"确认 (Confirm)"
+
+### 场景 2: 配置传统 Base64 订阅
+
+1. 点击"添加 (Add)"
+2. 基本信息:
+   - 名称: `Universal`
+   - User-Agent: `*`
+3. 模板:
+   - 输出格式: 选择 `Base64`
+   - 模板: 编写标准 vmess/vless URI 列表
+4. 设置为默认客户端
+5. 点击"确认 (Confirm)"
+
+### 场景 3: 限制订阅访问
+
+1. 打开"订阅配置"
+2. 启用"User-Agent 限制"
+3. 在"User-Agent 白名单"中添加:
+   ```
+   Clash
+   V2rayN
+   ClashX
+   Quantumult
+   ```
+4. 保存配置
+5. 只有白名单中的客户端能访问订阅
+
+### 场景 4: 使用自定义域名
+
+1. 打开"订阅配置"
+2. 在"订阅域名"中添加:
+   ```
+   sub.example.com
+   cdn.example.com
+   ```
+3. 配置"订阅路径": `/api/sub`
+4. 保存配置
+5. 用户可使用 `https://sub.example.com/api/sub/{token}` 访问订阅
+
+## 模板编写指南
+
+### Base64 格式示例
+```go
+{{range .Proxies}}{{.Type}}://{{.UUID}}@{{.Server}}:{{.Port}}?security={{.Security}}&sni={{.SNI}}#{{.Name}}
+{{end}}
+```
+
+### Clash YAML 格式示例
+```yaml
+proxies:
+{{range .Proxies}}
+  - name: {{.Name}}
+    type: {{.Type}}
+    server: {{.Server}}
+    port: {{.Port}}
+    {{if eq .Type "vless"}}uuid: {{.UUID}}{{end}}
+    {{if eq .Type "vmess"}}uuid: {{.UUID}}{{end}}
+    {{if eq .Type "trojan"}}password: {{.Password}}{{end}}
+{{end}}
+```
+
+### 条件判断示例
+```go
+{{range .Proxies}}
+{{if eq .Type "vless"}}
+vless://{{.UUID}}@{{.Server}}:{{.Port}}
+{{else if eq .Type "vmess"}}
+vmess://{{.UUID}}@{{.Server}}:{{.Port}}
+{{end}}
+{{end}}
+```
+
+## 注意事项
+
+1. **User-Agent 匹配**: 必须与客户端实际发送的 User-Agent 完全匹配,否则无法正确识别
+2. **模板语法**: 使用 Go Template 语法,语法错误会导致订阅生成失败
+3. **输出格式**: 确保模板输出与选择的格式匹配,如 YAML 格式需要正确的缩进
+4. **默认客户端**: 同时只能有一个默认客户端,设置新默认会取消旧的
+5. **域名配置**: 自定义域名需要在 DNS 和 Web 服务器中正确配置
+6. **路径更改**: 订阅路径更改后,需要重启系统以获得最佳性能
+7. **预览功能**: 使用预览功能测试模板是否正确生成
+8. **模板仓库**: 参考 GitHub 模板仓库获取更多示例和最佳实践
+
+</div>