📝 docs: Add documentation

2025-12-11 03:29:07 +00:00
parent 50e695a1bb
commit 99e7f6062d
135 changed files with 79115 additions and 8 deletions
@@ -0,0 +1,187 @@
+# Node Management
+
+Manage user-facing proxy nodes, configure node-server associations, entry addresses, and tags. Nodes are the actual endpoints users connect to, and one server can correspond to multiple nodes.
+
+## Page Components
+
+### Node List
+
+Display all node configuration information in table format.
+
+**Column Information:**
+- **Enabled**: Toggle switch to control whether the node is visible to users in real-time
+  - On: Node appears in subscriptions, users can connect
+  - Off: Node is hidden, users cannot connect
+  - Takes effect immediately without restart
+- **Name**: Node display name, shown in user's client
+- **Address:Port**: Entry address and port for user connections
+- **Server**: Shows associated server name and IP address
+  - Format: `Server Name:Server IP`
+- **Protocol:Port**: Proxy protocol type and server listening port
+  - Format: `Protocol Type:Server Port`
+  - Examples: `vless:443`, `vmess:80`, `trojan:8443`
+- **Tags**: Node grouping tags, displayed as badges
+  - Used for permission grouping and plan binding
+  - Used for traffic distribution policies
+  - Supports multiple tags
+
+**Operation Features:**
+- **Search**: Quickly filter nodes by keyword
+- **Sorting**: Adjust node display order by dragging rows, affects node order in user subscriptions
+- **Pagination**: Support paging for large number of nodes
+- **Batch Delete**: Delete multiple selected nodes
+
+**Individual Node Operations:**
+- **Edit**: Modify node configuration
+- **Delete**: Delete node
+- **Copy**: Copy node configuration to create new node (new node disabled by default)
+
+## Node Form
+
+A sidebar form that opens when clicking "Create" or "Edit".
+
+### Form Fields
+
+**1. Server** - Required
+- Select the physical server associated with the node
+- Dropdown shows: `Server Name (Server IP)`
+- Triggers smart autofill upon selection
+
+**2. Protocol** - Required
+- Select the proxy protocol to use
+- Dropdown only shows protocols enabled on selected server
+- Format: `Protocol Type (Port Number)`
+- Supported protocols: shadowsocks, vmess, vless, trojan, hysteria, tuic, anytls, naive, http, socks, mieru
+- Automatically fills corresponding port upon selection
+
+**3. Name** - Required
+- Display name of the node
+- Shown in user's proxy client
+- Supports autofill (from server name)
+
+**4. Address** - Required
+- Entry address for user connections
+- Can be domain name or IP address
+- Supports autofill (from server address)
+- Can be manually changed to CDN domain or other entry
+
+**5. Port** - Required
+- Entry port number for user connections
+- Range: 1-65535
+- Supports autofill (from protocol port)
+- Can be manually changed to different port (e.g., when using port forwarding)
+
+**6. Tags** - Optional
+- Node grouping tags, supports multiple tags
+- Can select from existing tags or enter new tags
+- Use Enter key or comma (,) to add multiple tags
+- Purpose:
+  - **Permission Grouping**: Bind with plans to control visible nodes for different plan users
+  - **Traffic Strategy**: Used for node traffic distribution and load balancing
+
+### Smart Autofill Mechanism
+
+The form has smart autofill functionality to improve configuration efficiency:
+
+**Trigger Conditions:**
+1. When selecting server
+2. When selecting protocol
+
+**Fill Rules:**
+- **After selecting server**:
+  - Name autofills with server name
+  - Address autofills with server IP
+  - Protocol automatically selects first available protocol
+  - Port autofills with corresponding protocol port
+
+- **After selecting protocol**:
+  - Port autofills with the protocol's port number
+
+**Manual Modification:**
+- After manually modifying any field, that field will no longer autofill
+- Reselecting server or protocol refreshes autofill status
+
+## Use Cases
+
+### Scenario 1: Create Basic Node
+1. Click "Create" button
+2. Select server (other fields autofill)
+3. Confirm or adjust autofilled configuration
+4. Click "Confirm"
+
+### Scenario 2: Create CDN Node
+1. Click "Create" button
+2. Select server
+3. Change name to: `Hong Kong 01 [CDN]`
+4. Change address to CDN domain: `hk01.cdn.example.com`
+5. Change port to CDN port: `443` or `80`
+6. Click "Confirm"
+
+### Scenario 3: Tag Group Management
+**For Plan Binding:**
+- Premium plan nodes: Add tags `premium`, `vip`
+- Standard plan nodes: Add tag `standard`
+- Trial plan nodes: Add tag `trial`
+- Bind tags in product management to show different nodes for different plans
+
+**For Region Classification:**
+- Hong Kong nodes: Add tags `hk`, `asia`
+- US nodes: Add tags `us`, `americas`
+- Japan nodes: Add tags `jp`, `asia`
+
+### Scenario 4: Batch Management
+1. Use search to filter specific nodes
+2. Check multiple nodes
+3. Click batch delete or batch operations
+4. Confirm operation
+
+## Relationship Between Nodes and Servers
+
+**Server:**
+- Physical server or VPS
+- Runs proxy service programs
+- Configures listening protocols and ports
+- One server can configure multiple protocols
+
+**Node:**
+- User-visible connection endpoint
+- Associated with a specific protocol on a server
+- Configures user connection entry address (can differ from server address)
+- One server can create multiple nodes
+
+**Example:**
+```
+Server: Hong Kong-HK01 (192.168.1.100)
+├── Protocol: vless:443
+├── Protocol: vmess:80
+└── Protocol: trojan:8443
+
+Node Configuration:
+1. Node Name: Hong Kong 01 [Direct]
+   - Server: Hong Kong-HK01
+   - Protocol: vless:443
+   - Address: 192.168.1.100
+   - Port: 443
+
+2. Node Name: Hong Kong 01 [CDN]
+   - Server: Hong Kong-HK01
+   - Protocol: vmess:80
+   - Address: hk01.cdn.example.com
+   - Port: 443 (CDN port)
+
+3. Node Name: Hong Kong 01 [VIP]
+   - Server: Hong Kong-HK01
+   - Protocol: trojan:8443
+   - Address: 192.168.1.100
+   - Port: 8443
+   - Tags: premium, vip
+```
+
+## Important Notes
+
+1. **Protocol Must Be Enabled**: Can only select protocols already enabled on the server; disabled protocols won't appear in dropdown
+2. **Delete Impact**: Deleting a node will cause users using that node to be unable to connect, proceed with caution
+3. **Disable vs Delete**: For temporarily taking a node offline, use "disable" instead of delete for easy restoration
+4. **Tag Planning**: Recommend planning tag system in advance for easier batch management of plans and nodes
+5. **Address Configuration**: When using CDN, ensure CDN is correctly configured to origin to server address
+6. **Port Mapping**: If entry port differs from server listening port (e.g., using port forwarding), ensure network layer is configured correctly
@@ -0,0 +1,261 @@
+# Product Management
+
+The Product Management module creates and manages subscription packages, which is the core of business operations.
+
+## Overview
+
+### Product List
+
+View and manage all product packages:
+
+- **Product Name**: Package display name
+- **Product Type**: Period/Traffic/Pay-as-you-go
+- **Price**: Product price and discount price
+- **Traffic Quota**: Total/Monthly traffic
+- **Validity**: Package duration (month/quarter/year)
+- **Node Groups**: Included node groups
+- **Status**: Active/Inactive/Sold out
+- **Sales**: Product sales quantity
+
+### Create Product
+
+Create new subscription package:
+
+#### Basic Info
+
+- **Product Name**: Package name users see
+- **Description**: Detailed product description
+- **Category**: Basic/Advanced/Premium
+- **Sort Order**: Product display order
+
+#### Pricing
+
+- **Original Price**: Product original price
+- **Sale Price**: Actual selling price
+- **Discount**: Discount percentage
+- **Currency**: CNY/USD, etc.
+- **Billing Cycle**: Monthly/Quarterly/Yearly
+
+#### Traffic Config
+
+- **Total Traffic**: Package total traffic quota
+- **Traffic Cycle**: One-time/Monthly reset
+- **Traffic Rate**: Traffic billing multiplier
+- **Overage**: Handling for traffic overage
+
+#### Duration
+
+- **Validity**: Package usage period
+- **Billing Cycle**: Monthly/Quarterly/Yearly
+- **Auto-renewal**: Support auto-renewal
+- **Renewal Discount**: Discount on renewal
+
+#### Node Config
+
+- **Included Groups**: Select node groups in package
+- **Device Limit**: Simultaneous device connection limit
+- **Speed Limit**: Per-user speed cap
+- **Available Regions**: Geographic restrictions
+
+#### Advanced Options
+
+- **Inventory**: Set product stock quantity
+- **Purchase Limit**: Per-person purchase limit
+- **New User Only**: Only new users can buy
+- **Trial Settings**: Provide free trial
+
+### Edit Product
+
+Modify existing product configuration:
+
+- Adjust price and discount
+- Update traffic quota
+- Modify node range
+- Change product status
+
+::: warning Note
+Product config changes don't affect existing users, only new orders.
+:::
+
+### Delete Product
+
+Confirm before deleting:
+
+- Are users currently using it
+- Are there pending orders
+- Should historical data be kept
+
+Recommend deactivating first, then delete after confirmation.
+
+## Product Categories
+
+### By Period
+
+#### Monthly
+
+- High flexibility for short-term users
+- Relatively higher price
+- Easy for users to try service
+
+#### Quarterly
+
+- Moderate price and duration
+- Balance flexibility and discount
+- Suitable for most users
+
+#### Yearly
+
+- Large discount
+- For long-term users
+- Reduce user churn
+
+#### Lifetime
+
+- One-time payment for permanent use
+- High price but good value
+- For loyal users
+
+### By Traffic
+
+#### Traffic Package
+
+- Fixed traffic quota
+- Stop when used up
+- For users with clear needs
+
+#### Unlimited
+
+- No traffic limit
+- May limit speed
+- For heavy users
+
+#### Pay-as-you-go
+
+- Pay for what you use
+- Flexible but potentially costly
+- For occasional users
+
+### By Tier
+
+#### Basic
+
+- Affordable price
+- Basic node groups
+- For light usage
+
+#### Advanced
+
+- Good value
+- More node options
+- For daily use
+
+#### Premium
+
+- Full node access
+- Highest speed and stability
+- For professional users
+
+## Pricing Strategy
+
+### Pricing Principles
+
+- **Cost-based**: Cover server and bandwidth costs
+- **Competition-based**: Reference industry pricing
+- **Value-based**: Price by value provided
+- **Psychological**: Use pricing psychology
+
+### Promotion Strategy
+
+#### Limited Time
+
+- Holiday promotions
+- Anniversary sales
+- New product launch discounts
+
+#### Coupons
+
+- Spend threshold coupons
+- Discount coupons
+- New user coupons
+
+#### Member Discounts
+
+- VIP user exclusive discounts
+- Cumulative purchase rebates
+- Referral rewards
+
+#### Bundle Packages
+
+- Multi-product combo discounts
+- Package upgrade discounts
+- Renewal discounts
+
+## Product Display
+
+### Product Page
+
+Optimize display to improve conversion:
+
+- **Clear Title**: Highlight features
+- **Detailed Description**: Explain advantages
+- **Price Comparison**: Show discount magnitude
+- **User Reviews**: Show real feedback
+- **Purchase Guide**: Clear buy button
+
+### Product Comparison
+
+Help users choose suitable package:
+
+- **Comparison Table**: Side-by-side comparison
+- **Recommendation Badge**: Mark popular/recommended
+- **Differentiation**: Highlight differences
+- **Use Cases**: Explain suitable scenarios
+
+## Product Analysis
+
+### Sales Data
+
+Analyze product sales:
+
+- **Sales Stats**: Product sales quantity
+- **Revenue Stats**: Revenue per product
+- **Conversion Rate**: Visit to purchase
+- **User Profile**: Buyer characteristics
+
+### Optimization
+
+Optimize products based on data:
+
+- **Price Adjustment**: Optimize pricing
+- **Config Optimization**: Adjust traffic and nodes
+- **Promotion Optimization**: Improve promotions
+- **Experience Optimization**: Enhance purchase flow
+
+## Inventory Management
+
+### Inventory Settings
+
+- **Stock Quantity**: Set product inventory
+- **Stock Alert**: Low stock reminder
+- **Restocking**: Auto-restock rules
+
+### Inventory Monitoring
+
+- **Real-time Stock**: View current inventory
+- **Stock Flow**: Inventory change records
+- **Sales Forecast**: Predict inventory needs
+
+## Best Practices
+
+- Offer multiple price tiers for different needs
+- Set clear product features and advantages
+- Regularly analyze sales data to optimize
+- Keep product info updated
+- Use promotions reasonably to boost sales
+- Collect user feedback for improvement
+
+## Next Steps
+
+- [Order Management](/admin/commerce/orders) - Process product orders
+- [Coupon Management](/admin/commerce/coupons) - Create promotions
+- [Marketing Management](/admin/commerce/marketing) - Promote products
@@ -0,0 +1,214 @@
+# Server Management
+
+Manage proxy servers' basic information, protocol configuration, and runtime status, as well as configure global node parameters.
+
+## Page Components
+
+The Server Management page consists of the following modules:
+
+### 1. Dynamic Multiplier
+
+A card at the top of the page for defining traffic billing multipliers for different time periods.
+
+**Features:**
+- **Time Slot Management**: Define multiple time periods, each containing:
+  - Start time: Format HH:MM:SS
+  - End time: Format HH:MM:SS
+  - Multiplier: Traffic billing multiplier for this period
+- **Dynamic Billing**: Apply different multipliers at different times, e.g., higher rates during peak hours
+- **Flexible Configuration**: Support adding, editing, and deleting time periods
+- **Immediate Effect**: Applied to traffic statistics immediately after saving
+
+**Use Cases:**
+- Peak/off-peak time-based billing
+- Holiday special billing
+- Limit traffic usage during peak hours
+
+### 2. Node Configuration
+
+A card at the top of the page for configuring node communication and global policies.
+
+**Basic Configuration:**
+- **Node Secret**: Authentication key for node-server communication
+- **Node Pull Interval**: Time interval (seconds) for nodes to pull configuration from server
+- **Node Push Interval**: Time interval (seconds) for nodes to push status to server
+- **Traffic Report Threshold**: Byte threshold for triggering traffic reports
+- **IP Strategy**: Choose prefer_ipv4 or prefer_ipv6
+
+**DNS Configuration:**
+- **Protocol**: tcp, udp, tls, https, quic
+- **Address**: DNS server address
+- **Domains**: List of domains to be resolved using this DNS
+- Support configuring multiple DNS servers
+
+**Outbound Rules:**
+Configure outbound proxies for specific traffic:
+- **Name**: Rule identifier
+- **Protocol**: Proxy protocol type
+- **Address**: Proxy server address
+- **Port**: Proxy server port
+- **Cipher**: Encryption method for protocols like Shadowsocks
+- **Password**: Proxy authentication password
+- **Rules**: Matching rules, such as domain names or IP ranges
+
+**Block Rules:**
+Configure list of domains or IPs to block, supporting wildcards and regex.
+
+### 3. Server List
+
+The main body of the page displays all servers in a table format.
+
+**Column Information:**
+- **ID**: Server unique identifier, displayed as a badge
+- **Name**: Server custom name
+- **Address**: Displays country/city/IP address using badge components
+- **Protocols**: Displays list of enabled protocols, each showing:
+  - Multiplier (e.g., 1.00x)
+  - Protocol type (e.g., vless, vmess, trojan, shadowsocks)
+  - Port number
+- **Status**: Online/offline status with dot indicator
+  - Green dot: Online
+  - Gray dot: Offline
+- **CPU**: CPU usage percentage, displayed as a progress bar
+- **Memory**: Memory usage percentage, displayed as a progress bar
+- **Disk**: Disk usage percentage, displayed as a progress bar
+- **Online Users**: Number of currently connected users
+
+**Operation Features:**
+- **Search**: Quickly filter servers by keyword
+- **Sorting**: Adjust server display order by dragging rows, sorting is saved to database
+- **Pagination**: Support paging for large number of servers
+- **Batch Delete**: Delete multiple selected servers (servers referenced by nodes cannot be deleted)
+
+**Individual Server Operations:**
+- **Edit**: Modify server configuration
+- **Connect**: Display one-click installation script
+- **Delete**: Delete server (disabled when referenced by nodes)
+- **Copy**: Copy server configuration to create a new server
+
+## Server Form
+
+A sidebar form that opens when clicking "Create" or "Edit".
+
+**Basic Information:**
+- **Name**: Required, server identifier name
+- **Country**: Server country code (e.g., CN, US, JP)
+- **City**: Server city
+- **Address**: Server IP address or domain
+
+**Protocol Configuration:**
+
+Support configuration of multiple proxy protocols, each expanded in accordion format. Protocol types used in nodes cannot be disabled.
+
+**Common Protocol Fields:**
+- **Enable**: Toggle switch to control whether to enable the protocol
+- **Port**: Listening port number
+- **Ratio**: Traffic billing multiplier, e.g., 1.5 means 1.5 times actual traffic
+- **Encryption/Security**: Varies depending on protocol type
+
+**Supported Protocol Types:**
+
+1. **Shadowsocks**
+   - Cipher: Encryption method (e.g., aes-256-gcm, chacha20-poly1305)
+   - Password: Authentication password, supports generating random password
+
+2. **Trojan**
+   - Password: Authentication password, supports generating random password
+
+3. **Vmess**
+   - UUID: User identifier, supports auto-generation
+   - Alter ID: Number of additional IDs
+
+4. **Vless**
+   - UUID: User identifier, supports auto-generation
+   - Flow: Flow control mode (e.g., xtls-rprx-vision)
+
+5. **Hysteria**
+   - Up/Down Speed: Upload/download speed limits
+   - Obfs Password: Obfuscation password
+
+6. **Hysteria2**
+   - Password: Authentication password
+   - Obfs Password: Obfuscation password
+
+7. **TUIC**
+   - UUID: User identifier
+   - Password: Authentication password
+   - Congestion Control: Congestion control algorithm (e.g., bbr, cubic)
+   - UDP Relay Mode: UDP relay mode
+
+**Transport Configuration:**
+
+Each protocol can be configured with different transport layers:
+- **TCP**: Basic TCP transport
+- **WS (WebSocket)**: WebSocket transport
+  - Path: WebSocket path
+  - Host: WebSocket Host header
+- **gRPC**: gRPC transport
+  - Service Name: gRPC service name
+- **HTTP/2**: HTTP/2 transport
+  - Path: Request path
+  - Host: Host header
+- **QUIC**: QUIC protocol transport
+- **HTTPUpgrade**: HTTP upgrade transport
+- **SplitHTTP**: Split HTTP transport
+- **XHTTP**: Extended HTTP transport
+
+**TLS Configuration:**
+- **TLS**: Whether to enable TLS
+- **Server Name**: SNI server name
+- **ALPN**: Application-Layer Protocol Negotiation (e.g., h2, http/1.1)
+- **Fingerprint**: TLS fingerprint (e.g., chrome, firefox, safari)
+- **Reality**: Reality protocol configuration
+  - Public Key: Public key
+  - Short ID: Short ID
+  - Spider X: Spider X parameter
+
+**Advanced Configuration:**
+- **Multiplex**: Multiplexing settings
+- **Encryption**: Additional encryption layer
+- **Flow Control**: Flow control parameters
+
+**Field Generation:**
+
+Some fields support auto-generation with a key icon:
+- **UUID**: Generate random UUID
+- **Password**: Generate random strong password
+- **Reality Key Pair**: Generate Public Key and Private Key
+- **Short ID**: Generate random short ID
+
+## One-Click Installation
+
+Click the "Connect" button to display the server node installation script.
+
+**Configuration:**
+- **API Host**: API address of the management panel (automatically obtained from current domain, can be manually modified)
+- **Server ID**: Unique ID of the current server (auto-filled)
+- **Secret Key**: Automatically obtained from node configuration
+
+**Install Command:**
+The generated bash script contains:
+```bash
+wget -N https://raw.githubusercontent.com/perfect-panel/ppanel-node/master/scripts/install.sh && bash install.sh --api-host [domain] --server-id [ID] --secret-key [key]
+```
+
+**Operations:**
+- Click "Copy and Close" to copy the script with one click and close the popup
+- Execute the script on the server to automatically install and connect the node
+
+## Online Users Viewing
+
+Click the "Online Users" number to view details of currently online users on the server.
+
+**Display Information:**
+- **User Account**: Link to user detail page
+- **Subscribe ID**: Subscription record ID
+- **Subscribe Name**: Plan name being used
+- **Traffic Usage**: Used traffic / Total traffic (displays "Unlimited" if unlimited)
+- **Expire Time**: Subscription expiration time, expired shows red "Expired" badge
+- **IP Address**: User connection IP, clickable to view IP information
+- **Connection Time**: Time when user established connection
+
+## Data Refresh
+
+Server status (CPU, Memory, Disk, Online Users) is updated in real-time according to the "Node Push Interval" set in "Node Configuration".
@@ -0,0 +1,59 @@
+# Template Variable Reference
+
+## Proxy Object Fields
+
+### Basic Fields
+- `Name` - Node name
+- `Server` - Server address
+- `Port` - Server port
+- `Type` - Protocol type
+- `Tags` - Tag array
+- `Sort` - Sort order
+
+### Security Options
+- `Security` - Security protocol
+- `SNI` - TLS server name
+- `AllowInsecure` - Allow insecure connections
+- `Fingerprint` - Client fingerprint
+- `RealityServerAddr` - Reality server address
+- `RealityPublicKey` - Reality public key
+- `RealityShortId` - Reality short ID
+
+### Transport Options
+- `Transport` - Transport protocol (ws, http, grpc)
+- `Host` - Host for WebSocket/HTTP
+- `Path` - Path for HTTP/HTTPS
+- `ServiceName` - gRPC service name
+
+### Protocol-Specific Fields
+
+#### Shadowsocks
+- `Method` - Encryption method
+- `Cipher` - Cipher algorithm
+- `ServerKey` - Server key
+
+#### Vmess/Vless
+- `UUID` - User ID
+- `Flow` - Flow control mode
+- `Encryption` - Encryption type
+
+#### Trojan
+- `Password` - Password
+
+#### Hysteria2
+- `UpMbps` - Upload bandwidth
+- `DownMbps` - Download bandwidth
+- `ObfsPassword` - Obfuscation password
+
+#### TUIC
+- `CongestionController` - Congestion control algorithm
+- `UDPRelayMode` - UDP relay mode
+
+## UserInfo Fields
+
+- `Password` - User password
+- `ExpiredAt` - Expiration time
+- `Download` - Downloaded traffic
+- `Upload` - Uploaded traffic
+- `Traffic` - Total traffic
+- `SubscribeURL` - Subscription link
@@ -0,0 +1,284 @@
+<div v-pre>
+
+# Subscribe Configuration
+
+Configure global subscription settings and manage subscription templates for client applications. Subscription configuration determines how users retrieve and use proxy node information.
+
+## Page Components
+
+The Subscribe Configuration page is divided into two main modules:
+
+### 1. Subscription Configuration
+
+A card at the top of the page for configuring global subscription system settings.
+
+**Configuration Options:**
+
+**Single Subscription Mode**
+- Type: Toggle switch
+- Function: Limit users to one active subscription
+- Note: Does not affect existing subscriptions, only applies to new ones
+- Use Case: Control subscription count, prevent account sharing
+
+**Wildcard Resolution**
+- Type: Toggle switch
+- Function: Enable wildcard domain resolution for subscriptions
+- Note: Allows using wildcard domains to access subscription links
+- Example: `*.example.com` can match `sub1.example.com`, `sub2.example.com`
+
+**Subscription Path**
+- Type: Text input
+- Function: Customize URL path for subscription endpoints
+- Format: `/your-custom-path`
+- Note: Better performance after system restart
+- Example: `/api/v1/subscribe` or `/sub`
+
+**Subscription Domain**
+- Type: Multi-line text
+- Function: Customize domains for subscription links
+- Format: One domain per line
+- Example:
+  ```
+  example.com
+  www.example.com
+  sub.example.com
+  ```
+- Use Cases:
+  - Use CDN domains
+  - Multi-domain load balancing
+  - Domain backup
+
+**User-Agent Restriction**
+- Type: Toggle switch
+- Function: Enable User-Agent based access control
+- Note: Only allow whitelisted clients to access subscriptions
+- Use Case: Prevent crawlers, restrict unauthorized access
+
+**User-Agent Whitelist**
+- Type: Multi-line text
+- Function: Configure allowed User-Agent list for subscription access
+- Format: One User-Agent per line
+- Example:
+  ```
+  ClashX
+  ClashForAndroid
+  Clash-verge
+  ```
+- Note: Configured application User-Agents are automatically included
+
+### 2. Client Management
+
+Manage subscription templates and download links for different proxy clients.
+
+**Table Column Information:**
+- **Default**: Toggle switch to set as default client
+  - Default client is prioritized on subscription page
+  - Only one default client at a time
+- **Client Name**: Displays client icon and name
+- **User-Agent**: Client identifier for distinguishing different clients
+- **Output Format**: Format type of subscription content
+  - Base64: Base64 encoded format
+  - YAML: YAML configuration file format
+  - JSON: JSON data format
+  - CONF: Configuration file format
+  - Plain Text: Plain text format
+- **Supported Platforms**: Shows operating systems supported by this client
+  - Windows, macOS, Linux, iOS, Android, HarmonyOS
+- **Description**: Detailed client description
+
+**Operation Features:**
+- **Preview**: View generated subscription template content
+  - Base64 format shows both original and decoded content
+  - Other formats display content directly
+  - Supports syntax highlighting
+- **Edit**: Modify client configuration
+- **Delete**: Delete client configuration
+- **Batch Delete**: Delete multiple selected clients
+
+**Top Toolbar:**
+- **Template Repo Link**: Jump to GitHub template repository
+  - URL: https://github.com/perfect-panel/subscription-template
+  - Provides subscription template examples and documentation
+- **Add**: Create new client configuration
+
+## Client Form
+
+A sidebar form that opens when clicking "Add" or "Edit", divided into three tabs.
+
+### Basic Info
+
+**Icon**
+- Type: URL input + Upload button
+- Format: Image URL or Base64 encoding
+- Example: `https://example.com/icon.png`
+- Function: Supports direct image upload, auto-converts to Base64
+
+**Name** - Required
+- Type: Text input
+- Function: Client display name
+- Example: `Clash for Windows`, `V2rayN`
+
+**User-Agent** - Required
+- Type: Text input
+- Function: Client identifier for distinguishing different clients
+- Example: `Clash`, `V2rayN`, `ClashX`
+- Important: Must match the actual User-Agent sent by the client
+
+**Description** - Optional
+- Type: Multi-line text
+- Function: Detailed client description
+- Content: Client features, usage instructions, etc.
+
+### Templates
+
+**Output Format** - Required
+- Type: Dropdown selection
+- Options:
+  - **Base64**: Traditional subscription format, suitable for most clients
+  - **YAML**: Clash series client configuration format
+  - **JSON**: JSON format configuration for clients supporting JSON
+  - **CONF**: Configuration file format, like Shadowrocket
+  - **Plain Text**: Plain text format
+
+**Scheme** - Optional
+- Type: Text input
+- Function: Custom URL Scheme
+- Example: `clash://`, `vmess://`
+- Purpose: One-click subscription import
+
+**Template** - Required
+- Type: Go Template editor
+- Function: Write subscription content using Go template syntax
+- Supports: Syntax highlighting, code completion
+- Variables:
+  - `{{.SiteName}}`: Site name
+  - `{{.SubscribeName}}`: Subscription name
+  - `{{.Proxies}}`: Node array
+  - `{{.UserInfo}}`: User information
+
+**Template Variable Reference**
+
+For detailed template variable reference, see: [Template Variable Reference](./subscribe-variables.md)
+
+UserInfo Fields:
+
+- `Password` - User password
+- `ExpiredAt` - Expiration time
+- `Download` - Downloaded traffic
+- `Upload` - Uploaded traffic
+- `Traffic` - Total traffic
+- `SubscribeURL` - Subscription link
+
+### Downloads
+
+Configure client download URLs for multiple platforms:
+
+- **Windows**: Windows platform download link
+- **macOS**: macOS platform download link
+- **Linux**: Linux platform download link
+- **iOS**: iOS platform download link
+- **Android**: Android platform download link
+- **HarmonyOS**: HarmonyOS download link
+
+Each platform is optional. When filled, corresponding platform badges will be displayed in the client list.
+
+## Use Cases
+
+### Scenario 1: Configure Clash Client
+
+1. Click "Add"
+2. Basic Info:
+   - Name: `Clash for Windows`
+   - User-Agent: `Clash`
+   - Icon: Upload Clash icon
+3. Templates:
+   - Output Format: Select `YAML`
+   - Template: Write Clash YAML configuration template
+4. Downloads:
+   - Windows: `https://github.com/Fndroid/clash_for_windows_pkg/releases`
+   - macOS: `https://github.com/yichengchen/clashX/releases`
+5. Click "Confirm"
+
+### Scenario 2: Configure Traditional Base64 Subscription
+
+1. Click "Add"
+2. Basic Info:
+   - Name: `Universal`
+   - User-Agent: `*`
+3. Templates:
+   - Output Format: Select `Base64`
+   - Template: Write standard vmess/vless URI list
+4. Set as default client
+5. Click "Confirm"
+
+### Scenario 3: Restrict Subscription Access
+
+1. Open "Subscription Configuration"
+2. Enable "User-Agent Restriction"
+3. Add to "User-Agent Whitelist":
+   ```
+   Clash
+   V2rayN
+   ClashX
+   Quantumult
+   ```
+4. Save configuration
+5. Only whitelisted clients can access subscriptions
+
+### Scenario 4: Use Custom Domain
+
+1. Open "Subscription Configuration"
+2. Add to "Subscription Domain":
+   ```
+   sub.example.com
+   cdn.example.com
+   ```
+3. Configure "Subscription Path": `/api/sub`
+4. Save configuration
+5. Users can access subscriptions via `https://sub.example.com/api/sub/{token}`
+
+## Template Writing Guide
+
+### Base64 Format Example
+```go
+{{range .Proxies}}{{.Type}}://{{.UUID}}@{{.Server}}:{{.Port}}?security={{.Security}}&sni={{.SNI}}#{{.Name}}
+{{end}}
+```
+
+### Clash YAML Format Example
+```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}}
+```
+
+### Conditional Logic Example
+```go
+{{range .Proxies}}
+{{if eq .Type "vless"}}
+vless://{{.UUID}}@{{.Server}}:{{.Port}}
+{{else if eq .Type "vmess"}}
+vmess://{{.UUID}}@{{.Server}}:{{.Port}}
+{{end}}
+{{end}}
+```
+
+## Important Notes
+
+1. **User-Agent Matching**: Must exactly match the User-Agent sent by the client, otherwise cannot be correctly identified
+2. **Template Syntax**: Uses Go Template syntax, syntax errors will cause subscription generation failure
+3. **Output Format**: Ensure template output matches selected format, e.g., YAML format requires correct indentation
+4. **Default Client**: Only one default client at a time, setting new default will cancel the old one
+5. **Domain Configuration**: Custom domains need to be correctly configured in DNS and web server
+6. **Path Changes**: After changing subscription path, system restart recommended for best performance
+7. **Preview Function**: Use preview to test if template generates correctly
+8. **Template Repository**: Refer to GitHub template repository for more examples and best practices
+
+</div>