admin/Xboard
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

翻译文档

Browse Source
This commit is contained in:
yinjianm
2026-02-22 04:13:42 +08:00
parent 267aeec5ba
commit 2d14e22322
13 changed files with 683 additions and 687 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -49
View File
@@ -9,19 +9,19 @@
</div> </div>
## 📖 Introduction ## 项目简介
Xboard is a modern panel system built on Laravel 11, focusing on providing a clean and efficient user experience. Xboard 是基于 Laravel 11 构建的现代化面板系统，专注于提供简洁高效的使用体验。
## ✨ Features ## 功能特性
- 🚀 Built with Laravel 12 + Octane for significant performance gains - 基于 Laravel 12 + Octane，显著提升性能
- 🎨 Redesigned admin interface (React + Shadcn UI) - 全新后台界面（React + Shadcn UI）
- 📱 Modern user frontend (Vue3 + TypeScript) - 现代化用户前端（Vue3 + TypeScript）
- 🐳 Ready-to-use Docker deployment solution - 开箱即用的 Docker 部署方案
- 🎯 Optimized system architecture for better maintainability - 优化系统架构，提升可维护性
## 🚀 Quick Start ## 快速开始
```bash ```bash
git clone -b compose --depth 1 https://github.com/Micah123321/Xboard && \ git clone -b compose --depth 1 https://github.com/Micah123321/Xboard && \
@@ -34,70 +34,70 @@ docker compose run -it --rm \
docker compose up -d docker compose up -d
``` ```
> After installation, visit: http://SERVER_IP:7001 > 安装完成后访问： http://SERVER_IP:7001
> ⚠️ Make sure to save the admin credentials shown during installation > 请务必保存安装过程中显示的管理员凭据
## 📖 Documentation ## 文档
### 🔄 Upgrade Notice ### 升级说明
> 🚨 **Important:** This version involves significant changes. Please strictly follow the upgrade documentation and backup your database before upgrading. Note that upgrading and migration are different processes, do not confuse them. > **重要：** 此版本包含较大变更。升级前请严格遵循升级文档并备份数据库。请注意，“升级”与“迁移”是不同流程，不要混淆。
### Development Guides ### 开发指南
- [Plugin Development Guide](./docs/en/development/plugin-development-guide.md) - Complete guide for developing XBoard plugins - [插件开发指南](./docs/en/development/plugin-development-guide.md) - Xboard 插件开发完整说明
- [Developer Guide (ZH-CN)](./docs/development-guide.zh-CN.md) - Local development, testing, running and build guide - [开发者指南（ZH-CN）](./docs/development-guide.zh-CN.md) - 本地开发、测试、运行与构建指南
- [V2bX Integration Guide (ZH-CN)](./docs/v2bx-integration.zh-CN.md) - Full Xboard ↔ V2bX integration guide - [V2bX 对接指南（ZH-CN）](./docs/v2bx-integration.zh-CN.md) - Xboard 到 V2bX 的完整对接指南
### Deployment Guides ### 部署指南
- [Deploy with 1Panel](./docs/en/installation/1panel.md) - [使用 1Panel 部署](./docs/en/installation/1panel.md)
- [Deploy with Docker Compose](./docs/en/installation/docker-compose.md) - [使用 Docker Compose 部署](./docs/en/installation/docker-compose.md)
- [Deploy with aaPanel](./docs/en/installation/aapanel.md) - [使用 aaPanel 部署](./docs/en/installation/aapanel.md)
- [Deploy with aaPanel + Docker](./docs/en/installation/aapanel-docker.md) (Recommended) - [使用 aaPanel + Docker 部署](./docs/en/installation/aapanel-docker.md)（推荐）
### Migration Guides ### 迁移指南
- [Migrate from v2board dev](./docs/en/migration/v2board-dev.md) - [从 v2board dev 迁移](./docs/en/migration/v2board-dev.md)
- [Migrate from v2board 1.7.4](./docs/en/migration/v2board-1.7.4.md) - [从 v2board 1.7.4 迁移](./docs/en/migration/v2board-1.7.4.md)
- [Migrate from v2board 1.7.3](./docs/en/migration/v2board-1.7.3.md) - [从 v2board 1.7.3 迁移](./docs/en/migration/v2board-1.7.3.md)
- [Upgrade from new-dev to latest Docker](./docs/en/migration/new-dev-to-latest-docker.md) - [从 new-dev 升级到最新 Docker 版本](./docs/en/migration/new-dev-to-latest-docker.md)
## 🛠️ Tech Stack ## 技术栈
- Backend: Laravel 11 + Octane - 后端：Laravel 11 + Octane
- Admin Panel: React + Shadcn UI + TailwindCSS - 管理后台：React + Shadcn UI + TailwindCSS
- User Frontend: Vue3 + TypeScript + NaiveUI - 用户前端：Vue3 + TypeScript + NaiveUI
- Deployment: Docker + Docker Compose - 部署方式：Docker + Docker Compose
- Caching: Redis + Octane Cache - 缓存：Redis + Octane Cache
## 📷 Preview ## 预览
![Admin Preview](./docs/images/admin.png) ![Admin Preview](./docs/images/admin.png)
![User Preview](./docs/images/user.png) ![User Preview](./docs/images/user.png)
## ⚠️ Disclaimer ## 免责声明
This project is for learning and communication purposes only. Users are responsible for any consequences of using this project. 本项目仅供学习与交流使用。使用本项目所产生的任何后果由使用者自行承担。
## 🌟 Maintenance Notice ## 维护说明
This project is currently under light maintenance. We will: 本项目当前处于轻度维护状态。我们将：
- Fix critical bugs and security issues - 修复关键 bug 与安全问题
- Review and merge important pull requests - 审核并合并重要的 Pull Request
- Provide necessary updates for compatibility - 提供必要的兼容性更新
However, new feature development may be limited. 但新功能开发可能会相对有限。
## 🔔 Important Notes ## 重要提示
1. Restart required after modifying admin path: 1. 修改后台路径后需要重启：
```bash ```bash
docker compose restart docker compose restart
``` ```
2. For aaPanel installations, restart the Octane daemon process 2. 使用 aaPanel 安装时，请重启 Octane 守护进程
## 🤝 Contributing ## 参与贡献
Issues and Pull Requests are welcome to help improve the project. 欢迎提交 Issue 和 Pull Request 来共同改进项目。
## 📈 Star History ## Star 历史
[![Stargazers over time](https://starchart.cc/Micah123321/Xboard.svg)](https://starchart.cc/Micah123321/Xboard) [![Stargazers over time](https://starchart.cc/Micah123321/Xboard.svg)](https://starchart.cc/Micah123321/Xboard)
docs/en/development/device-limit.md
+67 -67
View File
@@ -1,31 +1,31 @@
# Online Device Limit Design # 在线设备限制设计
## Overview ## 概述
This document describes the design and implementation of the online device limit feature in Xboard. 本文说明 Xboard 在线设备限制功能的设计与实现方案。
## Design Goals ## 设计目标
1. Accurate Control 1. 精准控制
- Precise counting of online devices - 精确统计在线设备数量
- Real-time monitoring of device status - 实时监控设备状态
- Accurate device identification - 准确识别设备身份
2. Performance Optimization 2. 性能优化
- Minimal impact on system performance - 对系统性能影响最小化
- Efficient device tracking - 高效追踪设备在线情况
- Optimized resource usage - 优化资源使用
3. User Experience 3. 用户体验
- Smooth connection experience - 保持连接过程平滑
- Clear error messages - 提供清晰错误提示
- Graceful handling of limit exceeded cases - 在超限场景下优雅处理
## Implementation Details ## 实现细节
### 1. Device Identification ### 1. 设备识别
#### Device ID Generation #### 设备 ID 生成
```php ```php
public function generateDeviceId($user, $request) { public function generateDeviceId($user, $request) {
return md5( return md5(
@@ -36,7 +36,7 @@ public function generateDeviceId($user, $request) {
} }
``` ```
#### Device Information Storage #### 设备信息存储
```php ```php
[ [
'device_id' => 'unique_device_hash', 'device_id' => 'unique_device_hash',
@@ -47,9 +47,9 @@ public function generateDeviceId($user, $request) {
] ]
``` ```
### 2. Connection Management ### 2. 连接管理
#### Connection Check #### 连接校验
```php ```php
public function checkDeviceLimit($user, $deviceId) { public function checkDeviceLimit($user, $deviceId) {
$onlineDevices = $this->getOnlineDevices($user->id); $onlineDevices = $this->getOnlineDevices($user->id);
@@ -64,7 +64,7 @@ public function checkDeviceLimit($user, $deviceId) {
} }
``` ```
#### Device Status Update #### 设备状态更新
```php ```php
public function updateDeviceStatus($userId, $deviceId) { public function updateDeviceStatus($userId, $deviceId) {
Redis::hset( Redis::hset(
@@ -78,9 +78,9 @@ public function updateDeviceStatus($userId, $deviceId) {
} }
``` ```
### 3. Cleanup Mechanism ### 3. 清理机制
#### Inactive Device Cleanup #### 非活跃设备清理
```php ```php
public function cleanupInactiveDevices() { public function cleanupInactiveDevices() {
$inactiveThreshold = now()->subMinutes(30); $inactiveThreshold = now()->subMinutes(30);
@@ -97,10 +97,10 @@ public function cleanupInactiveDevices() {
} }
``` ```
## Error Handling ## 错误处理
### Error Types ### 错误类型
1. Device Limit Exceeded 1. 设备数超限
```php ```php
class DeviceLimitExceededException extends Exception { class DeviceLimitExceededException extends Exception {
protected $message = 'Device limit exceeded'; protected $message = 'Device limit exceeded';
@@ -108,7 +108,7 @@ public function cleanupInactiveDevices() {
} }
``` ```
2. Invalid Device 2. 无效设备
```php ```php
class InvalidDeviceException extends Exception { class InvalidDeviceException extends Exception {
protected $message = 'Invalid device'; protected $message = 'Invalid device';
@@ -116,7 +116,7 @@ public function cleanupInactiveDevices() {
} }
``` ```
### Error Messages ### 错误消息
```php ```php
return [ return [
'device_limit_exceeded' => 'Maximum number of devices reached', 'device_limit_exceeded' => 'Maximum number of devices reached',
@@ -125,52 +125,52 @@ return [
]; ];
``` ```
## Performance Considerations ## 性能考虑
1. Cache Strategy 1. 缓存策略
- Use Redis for device tracking - 使用 Redis 追踪设备状态
- Implement cache expiration - 设置缓存过期机制
- Optimize cache structure - 优化缓存结构
2. Database Operations 2. 数据库操作
- Minimize database queries - 减少数据库查询次数
- Use batch operations - 使用批量操作
- Implement query optimization - 实施查询优化
3. Memory Management 3. 内存管理
- Efficient data structure - 采用高效数据结构
- Regular cleanup of expired data - 定期清理过期数据
- Memory usage monitoring - 持续监控内存使用
## Security Measures ## 安全措施
1. Device Verification 1. 设备校验
- Validate device information - 校验设备信息合法性
- Check for suspicious patterns - 检测可疑行为模式
- Implement rate limiting - 实施限流策略
2. Data Protection 2. 数据保护
- Encrypt sensitive information - 加密敏感信息
- Implement access control - 实施访问控制
- Regular security audits - 定期安全审计
## Future Improvements ## 后续优化方向
1. Enhanced Features 1. 功能增强
- Device management interface - 设备管理界面
- Device activity history - 设备活动历史
- Custom device names - 自定义设备名称
2. Performance Optimization 2. 性能优化
- Improved caching strategy - 改进缓存策略
- Better cleanup mechanism - 优化清理机制
- Reduced memory usage - 降低内存占用
3. Security Enhancements 3. 安全增强
- Advanced device fingerprinting - 更高级的设备指纹识别
- Fraud detection - 欺诈检测
- Improved encryption - 更完善的加密机制
## Conclusion ## 总结
This design provides a robust and efficient solution for managing online device limits while maintaining good performance and user experience. Regular monitoring and updates will ensure the system remains effective and secure. 该设计在保证性能和用户体验的同时，为在线设备数管理提供了稳健且高效的方案。通过持续监控和迭代优化，可长期保持系统的有效性与安全性。
docs/en/development/performance.md
+74 -74
View File
@@ -1,100 +1,100 @@
# Performance Comparison Report # 性能对比报告
## Test Environment ## 测试环境
### Hardware Configuration ### 硬件配置
- CPU: AMD EPYC 7K62 48-Core Processor - CPU: AMD EPYC 7K62 48-Core Processor
- Memory: 4GB - 内存: 4GB
- Disk: NVMe SSD - 磁盘: NVMe SSD
- Network: 1Gbps - 网络: 1Gbps
### Software Environment ### 软件环境
- OS: Ubuntu 22.04 LTS - 操作系统: Ubuntu 22.04 LTS
- PHP: 8.2 - PHP: 8.2
- MySQL: 5.7 - MySQL: 5.7
- Redis: 7.0 - Redis: 7.0
- Docker: Latest stable version - Docker: 最新稳定版
## Test Scenarios ## 测试场景
### 1. User Login Performance ### 1. 用户登录性能
- Concurrent users: 100 - 并发用户数: 100
- Test duration: 60 seconds - 测试时长: 60 秒
- Request type: POST - 请求类型: POST
- Target endpoint: `/api/v1/passport/auth/login` - 目标接口: `/api/v1/passport/auth/login`
Results: 测试结果:
- Average response time: 156ms - 平均响应时间: 156ms
- 95th percentile: 245ms - 95 分位响应时间: 245ms
- Maximum response time: 412ms - 最大响应时间: 412ms
- Requests per second: 642 - 每秒请求数: 642
### 2. User Dashboard Loading ### 2. 用户仪表盘加载
- Concurrent users: 100 - 并发用户数: 100
- Test duration: 60 seconds - 测试时长: 60 秒
- Request type: GET - 请求类型: GET
- Target endpoint: `/api/v1/user/dashboard` - 目标接口: `/api/v1/user/dashboard`
Results: 测试结果:
- Average response time: 89ms - 平均响应时间: 89ms
- 95th percentile: 167ms - 95 分位响应时间: 167ms
- Maximum response time: 289ms - 最大响应时间: 289ms
- Requests per second: 1121 - 每秒请求数: 1121
### 3. Node List Query ### 3. 节点列表查询
- Concurrent users: 100 - 并发用户数: 100
- Test duration: 60 seconds - 测试时长: 60 秒
- Request type: GET - 请求类型: GET
- Target endpoint: `/api/v1/user/server/nodes` - 目标接口: `/api/v1/user/server/nodes`
Results: 测试结果:
- Average response time: 134ms - 平均响应时间: 134ms
- 95th percentile: 223ms - 95 分位响应时间: 223ms
- Maximum response time: 378ms - 最大响应时间: 378ms
- Requests per second: 745 - 每秒请求数: 745
## Performance Optimization Measures ## 性能优化措施
1. Database Optimization 1. 数据库优化
- Added indexes for frequently queried fields - 为高频查询字段添加索引
- Optimized slow queries - 优化慢查询
- Implemented query caching - 引入查询缓存
2. Cache Strategy 2. 缓存策略
- Using Redis for session storage - 使用 Redis 存储会话
- Caching frequently accessed data - 缓存高频访问数据
- Implementing cache warming - 实施缓存预热
3. Code Optimization 3. 代码优化
- Reduced database queries - 减少数据库查询次数
- Optimized database connection pool - 优化数据库连接池
- Improved error handling - 改进错误处理流程
## Comparison with Previous Version ## 与上一版本对比
| Metric | Previous Version | Current Version | Improvement | | 指标 | 上一版本 | 当前版本 | 提升 |
|--------|-----------------|-----------------|-------------| |------|---------|---------|------|
| Login Response | 289ms | 156ms | 46% | | 登录响应 | 289ms | 156ms | 46% |
| Dashboard Loading | 178ms | 89ms | 50% | | 仪表盘加载 | 178ms | 89ms | 50% |
| Node List Query | 256ms | 134ms | 48% | | 节点列表查询 | 256ms | 134ms | 48% |
## Future Optimization Plans ## 后续优化计划
1. Infrastructure Level 1. 基础设施层
- Implement horizontal scaling - 实施横向扩展
- Add load balancing - 增加负载均衡
- Optimize network configuration - 优化网络配置
2. Application Level 2. 应用层
- Further optimize database queries - 进一步优化数据库查询
- Implement more efficient caching strategies - 实施更高效的缓存策略
- Reduce memory usage - 降低内存使用
3. Monitoring and Maintenance 3. 监控与维护
- Add performance monitoring - 增加性能监控
- Implement automatic scaling - 实施自动扩缩容
- Regular performance testing - 定期执行性能测试
## Conclusion ## 总结
The current version shows significant performance improvements compared to the previous version, with an average improvement of 48% in response times. The optimization measures implemented have effectively enhanced the system's performance and stability. 当前版本相较上一版本有明显性能提升，响应时间平均提升约 48%。已实施的优化措施有效增强了系统性能与稳定性。
docs/en/development/plugin-development-guide.md
+151 -155
View File
@@ -1,26 +1,26 @@
# XBoard Plugin Development Guide # XBoard 插件开发指南
## 📦 Plugin Structure ## 插件结构
Each plugin is an independent directory with the following structure: 每个插件都是一个独立目录，推荐结构如下：
``` ```
plugins/ plugins/
└── YourPlugin/ # Plugin directory (PascalCase naming) └── YourPlugin/ # 插件目录（PascalCase 命名）
├── Plugin.php # Main plugin class (required) ├── Plugin.php # 插件主类（必需）
├── config.json # Plugin configuration (required) ├── config.json # 插件配置（必需）
├── routes/ ├── routes/
│ └── api.php # API routes │ └── api.php # API 路由
├── Controllers/ # Controllers directory ├── Controllers/ # 控制器目录
│ └── YourController.php │ └── YourController.php
├── Commands/ # Artisan commands directory ├── Commands/ # Artisan 命令目录
│ └── YourCommand.php │ └── YourCommand.php
└── README.md # Documentation └── README.md # 文档说明
``` ```
## 🚀 Quick Start ## 快速开始
### 1. Create Configuration File `config.json` ### 1. 创建配置文件 `config.json`
```json ```json
{ {
@@ -49,7 +49,7 @@ plugins/
} }
``` ```
### 2. Create Main Plugin Class `Plugin.php` ### 2. 创建插件主类 `Plugin.php`
```php ```php
<?php <?php
@@ -75,9 +75,9 @@ class Plugin extends AbstractPlugin
} }
``` ```
### 3. Create Controller ### 3. 创建控制器
**Recommended approach: Extend PluginController** 推荐做法：继承 `PluginController`。
```php ```php
<?php <?php
@@ -102,7 +102,7 @@ class YourController extends PluginController
} }
``` ```
### 4. Create Routes `routes/api.php` ### 4. 创建路由 `routes/api.php`
```php ```php
<?php <?php
@@ -117,9 +117,9 @@ Route::group([
}); });
``` ```
## 🔧 Configuration Access ## 配置访问
In controllers, you can easily access plugin configuration: 在控制器中可直接访问插件配置：
```php ```php
// Get single configuration // Get single configuration
@@ -132,33 +132,33 @@ $allConfig = $this->getConfig();
$enabled = $this->isPluginEnabled(); $enabled = $this->isPluginEnabled();
``` ```
## 🎣 Hook System ## Hook 系统
### Popular Hooks (Recommended to follow) ### 常用 Hook（建议优先关注）
XBoard has built-in hooks for many business-critical nodes. Plugin developers can flexibly extend through `filter` or `listen` methods. Here are the most commonly used and valuable hooks: XBoard 在多个关键业务节点提供了内置 hook。插件可通过 `filter` 或 `listen` 扩展行为。
| Hook Name | Type | Typical Parameters | Description | | Hook 名称 | 类型 | 常见参数 | 说明 |
| ------------------------- | ------ | ----------------------- | ---------------- | | ------------------------- | ------ | ----------------------- | ---- |
| user.register.before | action | Request | Before user registration | | user.register.before | action | Request | 用户注册前 |
| user.register.after | action | User | After user registration | | user.register.after | action | User | 用户注册后 |
| user.login.after | action | User | After user login | | user.login.after | action | User | 用户登录后 |
| user.password.reset.after | action | User | After password reset | | user.password.reset.after | action | User | 密码重置后 |
| order.cancel.before | action | Order | Before order cancellation | | order.cancel.before | action | Order | 订单取消前 |
| order.cancel.after | action | Order | After order cancellation | | order.cancel.after | action | Order | 订单取消后 |
| payment.notify.before | action | method, uuid, request | Before payment callback | | payment.notify.before | action | method, uuid, request | 支付回调校验前 |
| payment.notify.verified | action | array | Payment callback verification successful | | payment.notify.verified | action | array | 支付回调校验成功 |
| payment.notify.failed | action | method, uuid, request | Payment callback verification failed | | payment.notify.failed | action | method, uuid, request | 支付回调校验失败 |
| traffic.reset.after | action | User | After traffic reset | | traffic.reset.after | action | User | 流量重置后 |
| ticket.create.after | action | Ticket | After ticket creation | | ticket.create.after | action | Ticket | 工单创建后 |
| ticket.reply.user.after | action | Ticket | After user replies to ticket | | ticket.reply.user.after | action | Ticket | 用户回复工单后 |
| ticket.close.after | action | Ticket | After ticket closure | | ticket.close.after | action | Ticket | 工单关闭后 |
> ⚡️ The hook system will continue to expand. Developers can always follow this documentation and the `php artisan hook:list` command to get the latest supported hooks. > hook 能力会持续扩展。可结合本文与 `php artisan hook:list` 获取最新支持列表。
### Filter Hooks ### Filter Hook
Used to modify data: 用于修改数据：
```php ```php
// In Plugin.php boot() method // In Plugin.php boot() method
@@ -169,9 +169,9 @@ $this->filter('guest_comm_config', function ($config) {
}); });
``` ```
### Action Hooks ### Action Hook
Used to execute operations: 用于执行动作：
```php ```php
$this->listen('user.created', function ($user) { $this->listen('user.created', function ($user) {
@@ -180,11 +180,11 @@ $this->listen('user.created', function ($user) {
}); });
``` ```
## 📝 Real Example: Telegram Login Plugin ## 实战示例：Telegram 登录插件
Using TelegramLogin plugin as an example to demonstrate complete implementation: 下面使用 TelegramLogin 插件展示完整实现思路。
**Main Plugin Class** (23 lines): ### 插件主类
```php ```php
<?php <?php
@@ -207,7 +207,7 @@ class Plugin extends AbstractPlugin
} }
``` ```
**Controller** (extends PluginController): ### 控制器（继承 `PluginController`）
```php ```php
class TelegramLoginController extends PluginController class TelegramLoginController extends PluginController
@@ -230,11 +230,9 @@ class TelegramLoginController extends PluginController
} }
``` ```
## ⏰ Plugin Scheduled Tasks (Scheduler) ## 插件定时任务（Scheduler）
Plugins can register their own scheduled tasks by implementing the `schedule(Schedule $schedule)` method in the main class. 插件可在主类中实现 `schedule(Schedule $schedule)` 方法来注册定时任务。
**Example:**
```php ```php
use Illuminate\Console\Scheduling\Schedule; use Illuminate\Console\Scheduling\Schedule;
@@ -252,27 +250,27 @@ class Plugin extends AbstractPlugin
} }
``` ```
- Just implement the `schedule()` method in Plugin.php. - 只需在 `Plugin.php` 中实现 `schedule()`。
- All plugin scheduled tasks will be automatically scheduled by the main program. - 主程序会自动调度所有插件任务。
- Supports all Laravel scheduler usage. - 支持 Laravel Scheduler 的全部能力。
## 🖥️ Plugin Artisan Commands ## 插件 Artisan 命令
Plugins can automatically register Artisan commands by creating command classes in the `Commands/` directory. 插件启用后，会自动加载 `Commands/` 目录中的命令类。
### Command Directory Structure ### 命令目录结构
``` ```
plugins/YourPlugin/ plugins/YourPlugin/
├── Commands/ ├── Commands/
│ ├── TestCommand.php # Test command │ ├── TestCommand.php # 测试命令
│ ├── BackupCommand.php # Backup command │ ├── BackupCommand.php # 备份命令
│ └── CleanupCommand.php # Cleanup command │ └── CleanupCommand.php # 清理命令
``` ```
### Create Command Class ### 创建命令类
**Example: TestCommand.php** 示例：`TestCommand.php`
```php ```php
<?php <?php
@@ -333,13 +331,13 @@ class TestCommand extends Command
} }
``` ```
### Automatic Command Registration ### 自动注册规则
- ✅ Automatically register all commands in `Commands/` directory when plugin is enabled - 插件启用时，自动注册 `Commands/` 目录下全部命令类。
- ✅ Command namespace automatically set to `Plugin\YourPlugin\Commands` - 命令命名空间自动按 `Plugin\YourPlugin\Commands` 解析。
- ✅ Supports all Laravel command features (arguments, options, interaction, etc.) - 支持 Laravel 命令全部能力（参数、选项、交互等）。
### Usage Examples ### 使用示例
```bash ```bash
# Test command # Test command
@@ -352,25 +350,25 @@ php artisan your-plugin:test info
php artisan your-plugin:test --help php artisan your-plugin:test --help
``` ```
### Best Practices ### 命令开发建议
1. **Command Naming**: Use `plugin-name:action` format, e.g., `telegram:test` 1. **命令命名**：使用 `plugin-name:action`，例如 `telegram:test`。
2. **Error Handling**: Wrap main logic with try-catch 2. **异常处理**：主流程建议统一 `try-catch`。
3. **Return Values**: Return 0 for success, 1 for failure 3. **返回码规范**：成功返回 `0`，失败返回 `1`。
4. **User Friendly**: Provide clear help information and error messages 4. **可用性**：提供清晰的帮助信息和错误提示。
5. **Type Declarations**: Use PHP 8.2 type declarations 5. **类型声明**：建议使用 PHP 8.2 类型声明。
## 🛠️ Development Tools ## 开发工具与基础能力
### Controller Base Class Selection ### 控制器基类选择
**Method 1: Extend PluginController (Recommended)** #### 方案一：继承 `PluginController`（推荐）
- Automatic configuration access: `$this->getConfig()` - 自动配置读取：`$this->getConfig()`
- Automatic status checking: `$this->beforePluginAction()` - 自动状态检查：`$this->beforePluginAction()`
- Unified error handling - 统一返回与错误处理
**Method 2: Use HasPluginConfig Trait** #### 方案二：使用 `HasPluginConfig` Trait
```php ```php
use App\Http\Controllers\Controller; use App\Http\Controllers\Controller;
@@ -388,37 +386,37 @@ class YourController extends Controller
} }
``` ```
### Configuration Types ### 配置类型
Supported configuration types: 支持以下配置类型：
- `string` - String - `string`：字符串
- `number` - Number - `number`：数字
- `boolean` - Boolean - `boolean`：布尔值
- `json` - Array - `json`：数组
- `yaml` - `yaml`
## 🎯 Best Practices ## 通用最佳实践
### 1. Concise Main Class ### 1. 保持主类简洁
- Plugin main class should be as concise as possible - `Plugin.php` 只保留启动相关逻辑。
- Mainly used for registering hooks and routes - 主要负责注册 hooks、路由、调度等入口。
- Complex logic should be placed in controllers or services - 复杂业务放到 Controller 或 Service。
### 2. Configuration Management ### 2. 统一配置管理
- Define all configuration items in `config.json` - 所有配置都在 `config.json` 明确定义。
- Use `$this->getConfig()` to access configuration - 通过 `$this->getConfig()` 读取。
- Provide default values for all configurations - 所有项建议提供默认值。
### 3. Route Design ### 3. 路由设计清晰
- Use semantic route prefixes - 使用语义化前缀。
- Place API routes in `routes/api.php` - API 路由放在 `routes/api.php`。
- Place Web routes in `routes/web.php` - Web 路由放在 `routes/web.php`。
### 4. Error Handling ### 4. 完善错误处理
```php ```php
public function handle(Request $request) public function handle(Request $request)
@@ -437,16 +435,16 @@ public function handle(Request $request)
} }
``` ```
## 🔍 Debugging Tips ## 调试技巧
### 1. Logging ### 1. 日志记录
```php ```php
\Log::info('Plugin operation', ['data' => $data]); \Log::info('Plugin operation', ['data' => $data]);
\Log::error('Plugin error', ['error' => $e->getMessage()]); \Log::error('Plugin error', ['error' => $e->getMessage()]);
``` ```
### 2. Configuration Checking ### 2. 配置校验
```php ```php
// Check required configuration // Check required configuration
@@ -455,7 +453,7 @@ if (!$this->getConfig('required_key')) {
} }
``` ```
### 3. Development Mode ### 3. 开发模式
```php ```php
if (config('app.debug')) { if (config('app.debug')) {
@@ -463,37 +461,35 @@ if (config('app.debug')) {
} }
``` ```
## 📋 Plugin Lifecycle ## 插件生命周期
1. **Installation**: Validate configuration, register to database 1. **安装**：校验配置并注册到数据库。
2. **Enable**: Load plugin, register hooks and routes 2. **启用**：加载插件并注册 hooks、路由、命令、调度。
3. **Running**: Handle requests, execute business logic 3. **运行**：处理请求并执行业务逻辑。
## 🎉 Summary ## 阶段总结
Based on TelegramLogin plugin practical experience: 结合 TelegramLogin 插件的实践经验：
- **Simplicity**: Main class only 23 lines, focused on core functionality - **简洁**：主类短小、职责单一。
- **Practicality**: Extends PluginController, convenient configuration access - **实用**：基于 `PluginController`，开发效率高。
- **Maintainability**: Clear directory structure, standard development patterns - **可维护**：目录结构清晰，模式统一。
- **Extensibility**: Hook-based architecture, easy to extend functionality - **可扩展**：通过 hooks 可快速扩展业务。
Following this guide, you can quickly develop plugins with complete functionality and concise code! 🚀 ## 插件 Artisan 命令完整指南
## 🖥️ Complete Plugin Artisan Commands Guide ### 功能亮点
### Feature Highlights - **自动注册**：插件启用时自动注册 `Commands/` 下命令。
- **命名空间隔离**：各插件命令互不冲突。
- **类型安全**：支持 PHP 8.2 类型声明。
- **异常处理**：可统一错误输出与退出码。
- **配置集成**：命令中可读取插件配置。
- **交互支持**：支持输入、确认、选择等交互流程。
✅ **Auto Registration**: Automatically register all commands in `Commands/` directory when plugin is enabled ### 真实案例
✅ **Namespace Isolation**: Each plugin's commands use independent namespaces
✅ **Type Safety**: Support PHP 8.2 type declarations
✅ **Error Handling**: Comprehensive exception handling and error messages
✅ **Configuration Integration**: Commands can access plugin configuration
✅ **Interaction Support**: Support user input and confirmation operations
### Real Case Demonstrations #### 1. Telegram 插件命令
#### 1. Telegram Plugin Commands
```bash ```bash
# Test Bot connection # Test Bot connection
@@ -506,7 +502,7 @@ php artisan telegram:test send --message="Hello World"
php artisan telegram:test info php artisan telegram:test info
``` ```
#### 2. TelegramExtra Plugin Commands #### 2. TelegramExtra 插件命令
```bash ```bash
# Show all statistics # Show all statistics
@@ -519,7 +515,7 @@ php artisan telegram-extra:stats users
php artisan telegram-extra:stats users --format=json php artisan telegram-extra:stats users --format=json
``` ```
#### 3. Example Plugin Commands #### 3. Example 插件命令
```bash ```bash
# Basic usage # Basic usage
@@ -529,9 +525,9 @@ php artisan example:hello
php artisan example:hello Bear --message="Welcome!" php artisan example:hello Bear --message="Welcome!"
``` ```
### Development Best Practices ### 命令开发规范
#### 1. Command Naming Conventions #### 1. 命名约定
```php ```php
// ✅ Recommended: Use plugin name as prefix // ✅ Recommended: Use plugin name as prefix
@@ -544,7 +540,7 @@ protected $signature = 'test {action}';
protected $signature = 'stats {type}'; protected $signature = 'stats {type}';
``` ```
#### 2. Error Handling Pattern #### 2. 异常处理模式
```php ```php
public function handle(): int public function handle(): int
@@ -559,7 +555,7 @@ public function handle(): int
} }
``` ```
#### 3. User Interaction #### 3. 交互能力
```php ```php
// Get user input // Get user input
@@ -575,7 +571,7 @@ if (!$this->confirm('Are you sure you want to execute this operation?')) {
$action = $this->choice('Choose operation', ['ping', 'send', 'info']); $action = $this->choice('Choose operation', ['ping', 'send', 'info']);
``` ```
#### 4. Configuration Access #### 4. 配置访问
```php ```php
// Access plugin configuration in commands // Access plugin configuration in commands
@@ -589,9 +585,9 @@ protected function getConfig(string $key, $default = null): mixed
} }
``` ```
### Advanced Usage ### 进阶用法
#### 1. Multi-Command Plugins #### 1. 多命令插件
```php ```php
// One plugin can have multiple commands // One plugin can have multiple commands
@@ -602,7 +598,7 @@ plugins/YourPlugin/Commands/
└── TestCommand.php # Test command └── TestCommand.php # Test command
``` ```
#### 2. Inter-Command Communication #### 2. 命令间通信
```php ```php
// Share data between commands through cache or database // Share data between commands through cache or database
@@ -610,7 +606,7 @@ Cache::put('plugin:backup:progress', $progress, 3600);
$progress = Cache::get('plugin:backup:progress'); $progress = Cache::get('plugin:backup:progress');
``` ```
#### 3. Scheduled Task Integration #### 3. 与定时任务联动
```php ```php
// Call commands in plugin's schedule method // Call commands in plugin's schedule method
@@ -621,9 +617,9 @@ public function schedule(Schedule $schedule): void
} }
``` ```
### Debugging Tips ### 命令调试建议
#### 1. Command Testing #### 1. 命令测试
```bash ```bash
# View command help # View command help
@@ -636,7 +632,7 @@ php artisan your-plugin:command --verbose
php artisan your-plugin:command --debug php artisan your-plugin:command --debug
``` ```
#### 2. Logging #### 2. 命令日志
```php ```php
// Log in commands // Log in commands
@@ -647,7 +643,7 @@ Log::info('Plugin command executed', [
]); ]);
``` ```
#### 3. Performance Monitoring #### 3. 性能监控
```php ```php
// Record command execution time // Record command execution time
@@ -657,35 +653,35 @@ $endTime = microtime(true);
$this->info("Execution time: " . round(($endTime - $startTime) * 1000, 2) . "ms"); $this->info("Execution time: " . round(($endTime - $startTime) * 1000, 2) . "ms");
``` ```
### Common Issues ### 常见问题
#### Q: Commands not showing in list? #### Q: 命令没有出现在列表里？
A: Check if plugin is enabled and ensure `Commands/` directory exists and contains valid command classes. A: 检查插件是否启用，并确认 `Commands/` 目录存在且命令类有效。
#### Q: Command execution failed? #### Q: 命令执行失败？
A: Check if command class namespace is correct and ensure it extends `Illuminate\Console\Command`. A: 检查命名空间是否正确，且类继承了 `Illuminate\Console\Command`。
#### Q: How to access plugin configuration? #### Q: 如何在命令中读取插件配置？
A: Get plugin instance through `PluginManager`, then call `getConfig()` method. A: 通过 `PluginManager` 获取插件实例，再调用 `getConfig()`。
#### Q: Can commands call other commands? #### Q: 命令能否调用其他命令？
A: Yes, use `Artisan::call()` method to call other commands. A: 可以，使用 `Artisan::call()`。
```php ```php
Artisan::call('other-plugin:command', ['arg' => 'value']); Artisan::call('other-plugin:command', ['arg' => 'value']);
``` ```
### Summary ### 总结
The plugin command system provides powerful extension capabilities for XBoard: 插件命令系统为 XBoard 提供了强扩展能力：
- 🚀 **Development Efficiency**: Quickly create management commands - **开发效率**：快速构建运维与管理命令
- 🔧 **Operational Convenience**: Automate daily operations - **运维便利**：支持自动化日常操作
- 📊 **Monitoring Capability**: Real-time system status viewing - **监控能力**：便于查看系统运行状态
- 🛠️ **Debug Support**: Convenient problem troubleshooting tools - **调试支持**：可快速定位与排查问题
By properly using plugin commands, you can greatly improve system maintainability and user experience! 🎉 合理使用插件命令，可以显著提升系统可维护性和使用体验。
docs/en/installation/1panel.md
+56 -56
View File
@@ -1,37 +1,37 @@
# Quick Deployment Guide for 1Panel # 1Panel 快速部署指南
This guide explains how to deploy Xboard using 1Panel. 本文档介绍如何使用 1Panel 部署 Xboard。
## 1. Environment Preparation ## 1. 环境准备
Install 1Panel: 安装 1Panel：
```bash ```bash
curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && \ curl -sSL https://resource.fit2cloud.com/1panel/package/quick_start.sh -o quick_start.sh && \
sudo bash quick_start.sh sudo bash quick_start.sh
``` ```
## 2. Environment Configuration ## 2. 环境配置
1. Install from App Store: 1. 从应用商店安装：
- OpenResty (any version) - OpenResty（任意版本）
- ⚠️ Check "External Port Access" to open firewall - 勾选“外部端口访问”以放行防火墙
- MySQL 5.7 (Use MariaDB for ARM architecture) - MySQL 5.7（ARM 架构请使用 MariaDB）
2. Create Database: 2. 创建数据库：
- Database name: `xboard` - 数据库名：`xboard`
- Username: `xboard` - 用户名：`xboard`
- Access rights: All hosts (%) - 权限：所有主机（%）
- Save the database password for installation - 请保存数据库密码，安装时需要使用
## 3. Deployment Steps ## 3. 部署步骤
1. Add Website: 1. 添加网站：
- Go to "Website" > "Create Website" > "Reverse Proxy" - 进入“网站” > “创建网站” > “反向代理”
- Domain: Enter your domain - 域名：填写你的域名
- Code: `xboard` - 代号：`xboard`
- Proxy address: `127.0.0.1:7001` - 代理地址：`127.0.0.1:7001`
2. Configure Reverse Proxy: 2. 配置反向代理：
```nginx ```nginx
location ^~ / { location ^~ / {
proxy_pass http://127.0.0.1:7001; proxy_pass http://127.0.0.1:7001;
@@ -50,24 +50,24 @@ location ^~ / {
} }
``` ```
3. Install Xboard: 3. 安装 Xboard：
```bash ```bash
# Enter site directory # 进入网站目录
cd /opt/1panel/apps/openresty/openresty/www/sites/xboard/index cd /opt/1panel/apps/openresty/openresty/www/sites/xboard/index
# Install Git (if not installed) # 安装 Git（未安装时执行）
## Ubuntu/Debian ## Ubuntu/Debian
apt update && apt install -y git apt update && apt install -y git
## CentOS/RHEL ## CentOS/RHEL
yum update && yum install -y git yum update && yum install -y git
# Clone repository # 克隆仓库
git clone -b compose --depth 1 https://github.com/Micah123321/Xboard ./ git clone -b compose --depth 1 https://github.com/Micah123321/Xboard ./
# Configure Docker Compose # 配置 Docker Compose
``` ```
4. Edit compose.yaml: 4. 编辑 compose.yaml：
```yaml ```yaml
services: services:
web: web:
@@ -119,60 +119,60 @@ networks:
external: true external: true
``` ```
5. Initialize Installation: 5. 初始化安装：
```bash ```bash
# Install dependencies and initialize # 安装依赖并初始化
docker compose run -it --rm web php artisan xboard:install docker compose run -it --rm web php artisan xboard:install
``` ```
⚠️ Important Configuration Notes: 重要配置说明：
1. Database Configuration 1. 数据库配置
- Database Host: Choose based on your deployment: - Database Host：按部署方式填写：
1. If database and Xboard are in the same network, use `mysql` 1. 如果数据库与 Xboard 在同一网络，填写 `mysql`
2. If connection fails, go to: Database -> Select Database -> Connection Info -> Container Connection, and use the "Host" value 2. 如果连接失败，进入：数据库 -> 选择数据库 -> 连接信息 -> 容器连接，使用其中的 Host 值
3. If using external database, enter your actual database host 3. 如果使用外部数据库，填写实际数据库地址
- Database Port: `3306` (default port unless configured otherwise) - Database Port：`3306`（默认端口，除非你另有配置）
- Database Name: `xboard` (the database created earlier) - Database Name：`xboard`（前面创建的数据库）
- Database User: `xboard` (the user created earlier) - Database User：`xboard`（前面创建的用户）
- Database Password: Enter the password saved earlier - Database Password：填写前面保存的密码
2. Redis Configuration 2. Redis 配置
- Choose to use built-in Redis - 选择使用内置 Redis
- No additional configuration needed - 无需额外配置
3. Administrator Information 3. 管理员信息
- Save the admin credentials displayed after installation - 保存安装完成后显示的管理员账号信息
- Note down the admin panel access URL - 记录管理后台访问地址
After configuration, start the services: 配置完成后，启动服务：
```bash ```bash
docker compose up -d docker compose up -d
``` ```
6. Start Services: 6. 启动服务：
```bash ```bash
docker compose up -d docker compose up -d
``` ```
## 4. Version Update ## 4. 版本更新
> 💡 Important Note: The update command varies depending on your installation version: > 重要说明：更新命令会因安装版本不同而有所区别：
> - If you installed recently (new version), use this command: > - 如果是最近安装（新版本），使用以下命令：
```bash ```bash
docker compose pull && \ docker compose pull && \
docker compose run -it --rm web php artisan xboard:update && \ docker compose run -it --rm web php artisan xboard:update && \
docker compose up -d docker compose up -d
``` ```
> - If you installed earlier (old version), replace `web` with `xboard`: > - 如果是较早安装（旧版本），请把 `web` 替换为 `xboard`：
```bash ```bash
docker compose pull && \ docker compose pull && \
docker compose run -it --rm xboard php artisan xboard:update && \ docker compose run -it --rm xboard php artisan xboard:update && \
docker compose up -d docker compose up -d
``` ```
> 🤔 Not sure which to use? Try the new version command first, if it fails, use the old version command. > 不确定该用哪个命令？先尝试新版本命令，失败后再使用旧版本命令。
## Important Notes ## 重要提示
- ⚠️ Ensure firewall is enabled to prevent port 7001 exposure to public - 请确保已开启防火墙，避免 7001 端口直接暴露到公网
- Service restart is required after code modifications - 代码修改后需要重启服务才能生效
- SSL certificate configuration is recommended for secure access - 建议配置 SSL 证书以保障访问安全
docs/en/installation/aapanel-docker.md
+61 -61
View File
@@ -1,88 +1,88 @@
# Xboard Deployment Guide for aaPanel + Docker Environment # aaPanel + Docker 环境下的 Xboard 部署指南
## Table of Contents ## 目录
1. [Requirements](#requirements) 1. [环境要求](#环境要求)
2. [Quick Deployment](#quick-deployment) 2. [快速部署](#快速部署)
3. [Detailed Configuration](#detailed-configuration) 3. [详细配置](#详细配置)
4. [Maintenance Guide](#maintenance-guide) 4. [维护指南](#维护指南)
5. [Troubleshooting](#troubleshooting) 5. [故障排查](#故障排查)
## Requirements ## 环境要求
### Hardware Requirements ### 硬件要求
- CPU: 1 core or above - CPU：1 核及以上
- Memory: 2GB or above - 内存：2GB 及以上
- Storage: 10GB+ available space - 存储：可用空间 10GB+
### Software Requirements ### 软件要求
- Operating System: Ubuntu 20.04+ / CentOS 7+ / Debian 10+ - 操作系统：Ubuntu 20.04+ / CentOS 7+ / Debian 10+
- Latest version of aaPanel - aaPanel 最新版本
- Docker and Docker Compose - Docker 和 Docker Compose
- Nginx (any version) - Nginx（任意版本）
- MySQL 5.7+ - MySQL 5.7+
## Quick Deployment ## 快速部署
### 1. Install aaPanel ### 1. 安装 aaPanel
```bash ```bash
curl -sSL https://www.aapanel.com/script/install_6.0_en.sh -o install_6.0_en.sh && \ curl -sSL https://www.aapanel.com/script/install_6.0_en.sh -o install_6.0_en.sh && \
bash install_6.0_en.sh aapanel bash install_6.0_en.sh aapanel
``` ```
### 2. Basic Environment Setup ### 2. 基础环境配置
#### 2.1 Install Docker #### 2.1 安装 Docker
```bash ```bash
# Install Docker # 安装 Docker
curl -sSL https://get.docker.com | bash curl -sSL https://get.docker.com | bash
# For CentOS systems, also run: # CentOS 系统还需要执行：
systemctl enable docker systemctl enable docker
systemctl start docker systemctl start docker
``` ```
#### 2.2 Install Required Components #### 2.2 安装必需组件
In the aaPanel dashboard, install: 在 aaPanel 面板中安装：
- Nginx (any version) - Nginx（任意版本）
- MySQL 5.7 - MySQL 5.7
- ⚠️ PHP and Redis are not required - PHP 和 Redis 不需要安装
### 3. Site Configuration ### 3. 网站配置
#### 3.1 Create Website #### 3.1 创建网站
1. Navigate to: aaPanel > Website > Add site 1. 进入：aaPanel > 网站 > 添加站点
2. Fill in the information: 2. 填写信息：
- Domain: Enter your site domain - 域名：填写你的网站域名
- Database: Select MySQL - 数据库：选择 MySQL
- PHP Version: Select Pure Static - PHP 版本：选择纯静态
#### 3.2 Deploy Xboard #### 3.2 部署 Xboard
```bash ```bash
# Enter site directory # 进入网站目录
cd /www/wwwroot/your-domain cd /www/wwwroot/your-domain
# Clean directory # 清理目录
chattr -i .user.ini chattr -i .user.ini
rm -rf .htaccess 404.html 502.html index.html .user.ini rm -rf .htaccess 404.html 502.html index.html .user.ini
# Clone repository # 克隆仓库
git clone https://github.com/Micah123321/Xboard.git ./ git clone https://github.com/Micah123321/Xboard.git ./
# Prepare configuration file # 准备配置文件
cp compose.sample.yaml compose.yaml cp compose.sample.yaml compose.yaml
# Install dependencies and initialize # 安装依赖并初始化
docker compose run -it --rm web sh init.sh docker compose run -it --rm web sh init.sh
``` ```
> ⚠️ Please save the admin dashboard URL, username, and password shown after installation > 请保存安装完成后显示的管理后台地址、用户名和密码
#### 3.3 Start Services #### 3.3 启动服务
```bash ```bash
docker compose up -d docker compose up -d
``` ```
#### 3.4 Configure Reverse Proxy #### 3.4 配置反向代理
Add the following content to your site configuration: 将以下内容添加到网站配置：
```nginx ```nginx
location ^~ / { location ^~ / {
proxy_pass http://127.0.0.1:7001; proxy_pass http://127.0.0.1:7001;
@@ -101,18 +101,18 @@ location ^~ / {
} }
``` ```
## Maintenance Guide ## 维护指南
### Version Updates ### 版本更新
> 💡 Important Note: Update commands may vary depending on your installed version: > 重要说明：更新命令会因你安装的版本不同而有所区别：
> - For recent installations (new version), use: > - 如果是最近安装（新版本），使用：
```bash ```bash
docker compose pull && \ docker compose pull && \
docker compose run -it --rm web sh update.sh && \ docker compose run -it --rm web sh update.sh && \
docker compose up -d docker compose up -d
``` ```
> - For older installations, replace `web` with `xboard`: > - 如果是较早安装（旧版本），请把 `web` 替换为 `xboard`：
```bash ```bash
git config --global --add safe.directory $(pwd) git config --global --add safe.directory $(pwd)
git fetch --all && git reset --hard origin/master && git pull origin master git fetch --all && git reset --hard origin/master && git pull origin master
@@ -120,18 +120,18 @@ docker compose pull && \
docker compose run -it --rm xboard sh update.sh && \ docker compose run -it --rm xboard sh update.sh && \
docker compose up -d docker compose up -d
``` ```
> 🤔 Not sure which to use? Try the new version command first, if it fails, use the old version command. > 不确定该用哪个命令？先尝试新版本命令，失败后再使用旧版本命令。
### Routine Maintenance ### 日常维护
- Regular log checking: `docker compose logs` - 定期查看日志：`docker compose logs`
- Monitor system resource usage - 监控系统资源使用情况
- Regular backup of database and configuration files - 定期备份数据库和配置文件
## Troubleshooting ## 故障排查
If you encounter any issues during installation or operation, please check: 如果在安装或运行中遇到问题，请检查：
1. System requirements are met 1. 系统要求是否满足
2. All required ports are available 2. 所有必需端口是否可用
3. Docker services are running properly 3. Docker 服务是否正常运行
4. Nginx configuration is correct 4. Nginx 配置是否正确
5. Check logs for detailed error messages 5. 查看日志以获取详细报错信息
docs/en/installation/aapanel.md
+80 -80
View File
@@ -1,46 +1,46 @@
# Xboard Deployment Guide for aaPanel Environment # aaPanel 环境下的 Xboard 部署指南
## Table of Contents ## 目录
1. [Requirements](#requirements) 1. [环境要求](#环境要求)
2. [Quick Deployment](#quick-deployment) 2. [快速部署](#快速部署)
3. [Detailed Configuration](#detailed-configuration) 3. [详细配置](#详细配置)
4. [Maintenance Guide](#maintenance-guide) 4. [维护指南](#维护指南)
5. [Troubleshooting](#troubleshooting) 5. [故障排查](#故障排查)
## Requirements ## 环境要求
### Hardware Requirements ### 硬件要求
- CPU: 1 core or above - CPU：1 核及以上
- Memory: 2GB or above - 内存：2GB 及以上
- Storage: 10GB+ available space - 存储：可用空间 10GB+
### Software Requirements ### 软件要求
- Operating System: Ubuntu 20.04+ / Debian 10+ (⚠️ CentOS 7 is not recommended) - 操作系统：Ubuntu 20.04+ / Debian 10+（CentOS 7 不推荐）
- Latest version of aaPanel - aaPanel 最新版本
- PHP 8.2 - PHP 8.2
- MySQL 5.7+ - MySQL 5.7+
- Redis - Redis
- Nginx (any version) - Nginx（任意版本）
## Quick Deployment ## 快速部署
### 1. Install aaPanel ### 1. 安装 aaPanel
```bash ```bash
URL=https://www.aapanel.com/script/install_6.0_en.sh && \ URL=https://www.aapanel.com/script/install_6.0_en.sh && \
if [ -f /usr/bin/curl ];then curl -ksSO "$URL" ;else wget --no-check-certificate -O install_6.0_en.sh "$URL";fi && \ if [ -f /usr/bin/curl ];then curl -ksSO "$URL" ;else wget --no-check-certificate -O install_6.0_en.sh "$URL";fi && \
bash install_6.0_en.sh aapanel bash install_6.0_en.sh aapanel
``` ```
### 2. Basic Environment Setup ### 2. 基础环境配置
#### 2.1 Install LNMP Environment #### 2.1 安装 LNMP 环境
In the aaPanel dashboard, install: 在 aaPanel 面板中安装：
- Nginx (any version) - Nginx（任意版本）
- MySQL 5.7 - MySQL 5.7
- PHP 8.2 - PHP 8.2
#### 2.2 Install PHP Extensions #### 2.2 安装 PHP 扩展
Required PHP extensions: 必需的 PHP 扩展：
- redis - redis
- fileinfo - fileinfo
- swoole - swoole
@@ -48,41 +48,41 @@ Required PHP extensions:
- event - event
- mbstring - mbstring
#### 2.3 Enable Required PHP Functions #### 2.3 启用所需 PHP 函数
Functions that need to be enabled: 需要启用的函数：
- putenv - putenv
- proc_open - proc_open
- pcntl_alarm - pcntl_alarm
- pcntl_signal - pcntl_signal
### 3. Site Configuration ### 3. 网站配置
#### 3.1 Create Website #### 3.1 创建网站
1. Navigate to: aaPanel > Website > Add site 1. 进入：aaPanel > 网站 > 添加站点
2. Fill in the information: 2. 填写信息：
- Domain: Enter your site domain - 域名：填写你的网站域名
- Database: Select MySQL - 数据库：选择 MySQL
- PHP Version: Select 8.2 - PHP 版本：选择 8.2
#### 3.2 Deploy Xboard #### 3.2 部署 Xboard
```bash ```bash
# Enter site directory # 进入网站目录
cd /www/wwwroot/your-domain cd /www/wwwroot/your-domain
# Clean directory # 清理目录
chattr -i .user.ini chattr -i .user.ini
rm -rf .htaccess 404.html 502.html index.html .user.ini rm -rf .htaccess 404.html 502.html index.html .user.ini
# Clone repository # 克隆仓库
git clone https://github.com/Micah123321/Xboard.git ./ git clone https://github.com/Micah123321/Xboard.git ./
# Install dependencies # 安装依赖
sh init.sh sh init.sh
``` ```
#### 3.3 Configure Site #### 3.3 配置网站
1. Set running directory to `/public` 1. 运行目录设置为 `/public`
2. Add rewrite rules: 2. 添加伪静态规则：
```nginx ```nginx
location /downloads { location /downloads {
} }
@@ -99,33 +99,33 @@ location ~ .*\.(js|css)?$
} }
``` ```
## Detailed Configuration ## 详细配置
### 1. Configure Daemon Process ### 1. 配置守护进程
1. Install Supervisor 1. 安装 Supervisor
2. Add queue daemon process: 2. 添加队列守护进程：
- Name: `Xboard` - 名称：`Xboard`
- Run User: `www` - 运行用户：`www`
- Running Directory: Site directory - 运行目录：网站目录
- Start Command: `php artisan horizon` - 启动命令：`php artisan horizon`
- Process Count: 1 - 进程数量：1
### 2. Configure Scheduled Tasks ### 2. 配置计划任务
- Type: Shell Script - 类型：Shell 脚本
- Task Name: v2board - 任务名称：v2board
- Run User: www - 执行用户：www
- Frequency: 1 minute - 执行周期：每 1 分钟
- Script Content: `php /www/wwwroot/site-directory/artisan schedule:run` - 脚本内容：`php /www/wwwroot/site-directory/artisan schedule:run`
### 3. Octane Configuration (Optional) ### 3. Octane 配置（可选）
#### 3.1 Add Octane Daemon Process #### 3.1 添加 Octane 守护进程
- Name: Octane - 名称：Octane
- Run User: www - 运行用户：www
- Running Directory: Site directory - 运行目录：网站目录
- Start Command: `/www/server/php/82/bin/php artisan octane:start --port 7010` - 启动命令：`/www/server/php/82/bin/php artisan octane:start --port 7010`
- Process Count: 1 - 进程数量：1
#### 3.2 Octane-specific Rewrite Rules #### 3.2 Octane 专用伪静态规则
```nginx ```nginx
location ~* \.(jpg|jpeg|png|gif|js|css|svg|woff2|woff|ttf|eot|wasm|json|ico)$ { location ~* \.(jpg|jpeg|png|gif|js|css|svg|woff2|woff|ttf|eot|wasm|json|ico)$ {
} }
@@ -146,30 +146,30 @@ location ~ .* {
} }
``` ```
## Maintenance Guide ## 维护指南
### Version Updates ### 版本更新
```bash ```bash
# Enter site directory # 进入网站目录
cd /www/wwwroot/your-domain cd /www/wwwroot/your-domain
# Execute update script # 执行更新脚本
git fetch --all && git reset --hard origin/master && git pull origin master git fetch --all && git reset --hard origin/master && git pull origin master
sh update.sh sh update.sh
# If Octane is enabled, restart the daemon process # 如果启用了 Octane，请重启守护进程
# aaPanel > App Store > Tools > Supervisor > Restart Octane # aaPanel > 应用商店 > 工具 > Supervisor > 重启 Octane
``` ```
### Routine Maintenance ### 日常维护
- Regular log checking - 定期检查日志
- Monitor system resource usage - 监控系统资源使用情况
- Regular backup of database and configuration files - 定期备份数据库和配置文件
## Troubleshooting ## 故障排查
### Common Issues ### 常见问题
1. Changes to admin path require service restart to take effect 1. 修改后台路径后，需要重启服务才会生效
2. Any code changes after enabling Octane require restart to take effect 2. 启用 Octane 后，任何代码变更都需要重启才会生效
3. When PHP extension installation fails, check if PHP version is correct 3. PHP 扩展安装失败时，请检查 PHP 版本是否正确
4. For database connection failures, check database configuration and permissions 4. 数据库连接失败时，请检查数据库配置和权限
docs/en/installation/docker-compose.md
+27 -27
View File
@@ -1,29 +1,29 @@
# Quick Deployment Guide with Docker Compose # Docker Compose 快速部署指南
This guide explains how to quickly deploy Xboard using Docker Compose. By default, it uses SQLite database, eliminating the need for a separate MySQL installation. 本文档介绍如何使用 Docker Compose 快速部署 Xboard。默认使用 SQLite 数据库，无需额外安装 MySQL。
### 1. Environment Preparation ### 1. 环境准备
Install Docker: 安装 Docker：
```bash ```bash
curl -sSL https://get.docker.com | bash curl -sSL https://get.docker.com | bash
# For CentOS systems, also run: # CentOS 系统还需要执行：
systemctl enable docker systemctl enable docker
systemctl start docker systemctl start docker
``` ```
### 2. Deployment Steps ### 2. 部署步骤
1. Get project files: 1. 获取项目文件：
```bash ```bash
git clone -b compose --depth 1 https://github.com/Micah123321/Xboard git clone -b compose --depth 1 https://github.com/Micah123321/Xboard
cd Xboard cd Xboard
``` ```
2. Install database: 2. 安装数据库：
- Quick installation (Recommended for beginners) - 快速安装（推荐新手）
```bash ```bash
docker compose run -it --rm \ docker compose run -it --rm \
-e ENABLE_SQLITE=true \ -e ENABLE_SQLITE=true \
@@ -31,47 +31,47 @@ docker compose run -it --rm \
-e ADMIN_ACCOUNT=admin@demo.com \ -e ADMIN_ACCOUNT=admin@demo.com \
web php artisan xboard:install web php artisan xboard:install
``` ```
- Custom configuration installation (Advanced users) - 自定义配置安装（高级用户）
```bash ```bash
docker compose run -it --rm web php artisan xboard:install docker compose run -it --rm web php artisan xboard:install
``` ```
> Please save the admin dashboard URL, username, and password shown after installation > 请保存安装完成后显示的管理后台地址、用户名和密码
3. Start services: 3. 启动服务：
```bash ```bash
docker compose up -d docker compose up -d
``` ```
4. Access the site: 4. 访问站点：
- Default port: 7001 - 默认端口：7001
- Website URL: http://your-server-ip:7001 - 访问地址：http://your-server-ip:7001
### 3. Version Updates ### 3. 版本更新
> 💡 Important Note: Update commands may vary depending on your installed version: > 重要说明：更新命令会因你安装的版本不同而有所区别：
> - For recent installations (new version), use: > - 如果是最近安装（新版本），使用：
```bash ```bash
cd Xboard cd Xboard
docker compose pull && \ docker compose pull && \
docker compose run -it --rm web php artisan xboard:update && \ docker compose run -it --rm web php artisan xboard:update && \
docker compose up -d docker compose up -d
``` ```
> - For older installations, replace `web` with `xboard`: > - 如果是较早安装（旧版本），请把 `web` 替换为 `xboard`：
```bash ```bash
cd Xboard cd Xboard
docker compose pull && \ docker compose pull && \
docker compose run -it --rm xboard php artisan xboard:update && \ docker compose run -it --rm xboard php artisan xboard:update && \
docker compose up -d docker compose up -d
``` ```
> 🤔 Not sure which to use? Try the new version command first, if it fails, use the old version command. > 不确定该用哪个命令？先尝试新版本命令，失败后再使用旧版本命令。
### 4. Version Rollback ### 4. 版本回滚
1. Modify the version number in `docker-compose.yaml` to the version you want to roll back to 1. 修改 `docker-compose.yaml` 中的版本号为你要回滚的版本
2. Execute: `docker compose up -d` 2. 执行：`docker compose up -d`
### Important Notes ### 重要提示
- If you need to use MySQL, please install it separately and redeploy - 如果需要使用 MySQL，请单独安装后重新部署
- Code changes require service restart to take effect - 代码有变更时，需要重启服务后才会生效
- You can configure Nginx reverse proxy to use port 80 - 可以配置 Nginx 反向代理以使用 80 端口
docs/en/migration/config.md
+18 -18
View File
@@ -1,54 +1,54 @@
# Configuration Migration Guide # 配置迁移指南
This guide explains how to migrate configuration files from v2board to Xboard. Xboard stores configurations in the database instead of files. 本指南说明如何将配置文件从 v2board 迁移到 Xboard。Xboard 将配置存储在数据库中，而不是文件中。
### 1. Docker Compose Environment ### 1. Docker Compose 环境
1. Prepare configuration file: 1. 准备配置文件：
```bash ```bash
# Create config directory # 创建 config 目录
mkdir config mkdir config
# Copy old configuration file # 复制旧配置文件
cp old-project-path/config/v2board.php config/ cp old-project-path/config/v2board.php config/
``` ```
2. Modify `docker-compose.yaml`, uncomment the following line: 2. 修改 `docker-compose.yaml`，取消注释以下行：
```yaml ```yaml
- ./config/v2board.php:/www/config/v2board.php - ./config/v2board.php:/www/config/v2board.php
``` ```
3. Execute migration: 3. 执行迁移：
```bash ```bash
docker compose run -it --rm web php artisan migrateFromV2b config docker compose run -it --rm web php artisan migrateFromV2b config
``` ```
### 2. aaPanel Environment ### 2. aaPanel 环境
1. Copy configuration file: 1. 复制配置文件：
```bash ```bash
cp old-project-path/config/v2board.php config/v2board.php cp old-project-path/config/v2board.php config/v2board.php
``` ```
2. Execute migration: 2. 执行迁移：
```bash ```bash
php artisan migrateFromV2b config php artisan migrateFromV2b config
``` ```
### 3. aaPanel + Docker Environment ### 3. aaPanel + Docker 环境
1. Copy configuration file: 1. 复制配置文件：
```bash ```bash
cp old-project-path/config/v2board.php config/v2board.php cp old-project-path/config/v2board.php config/v2board.php
``` ```
2. Execute migration: 2. 执行迁移：
```bash ```bash
docker compose run -it --rm web php artisan migrateFromV2b config docker compose run -it --rm web php artisan migrateFromV2b config
``` ```
### Important Notes ### 重要说明
- After modifying the admin path, service restart is required: - 修改后台路径后需要重启服务：
- Docker environment: `docker compose restart` - Docker 环境：`docker compose restart`
- aaPanel environment: Restart the Octane daemon process - aaPanel 环境：重启 Octane 守护进程
docs/en/migration/new-dev-to-latest-docker.md
+10 -10
View File
@@ -1,21 +1,21 @@
# Upgrade from `new-dev` to Latest Docker Version # 从 `new-dev` 升级到最新 Docker 版本
This guide uses Docker Compose to move from an old `new-dev` deployment flow to the latest version. 本指南使用 Docker Compose，将旧的 `new-dev` 部署流程迁移到最新版本。
## 1. Get the project ## 1. 获取项目
```bash ```bash
git clone -b compose --depth 1 https://github.com/Micah123321/Xboard Xboard-new git clone -b compose --depth 1 https://github.com/Micah123321/Xboard Xboard-new
cd Xboard-new cd Xboard-new
``` ```
If your local file is `compose.sample.yaml`, create `compose.yaml` first: 如果你的本地文件是 `compose.sample.yaml`，请先创建 `compose.yaml`：
```bash ```bash
cp compose.sample.yaml compose.yaml cp compose.sample.yaml compose.yaml
``` ```
## 2. Initialize with built-in SQLite + Redis ## 2. 使用内置 SQLite + Redis 初始化
```bash ```bash
docker compose run -it --rm \ docker compose run -it --rm \
@@ -25,9 +25,9 @@ docker compose run -it --rm \
web php artisan xboard:install web php artisan xboard:install
``` ```
## 3. Update `.env` to MySQL configuration ## 3. 将 `.env` 更新为 MySQL 配置
Edit `.env` and switch database settings to MySQL: 编辑 `.env`，将数据库配置切换为 MySQL：
```env ```env
DB_CONNECTION=mysql DB_CONNECTION=mysql
@@ -38,19 +38,19 @@ DB_USERNAME=your_user
DB_PASSWORD=your_password DB_PASSWORD=your_password
``` ```
Then run: 然后执行：
```bash ```bash
docker compose run -it --rm web php artisan xboard:update docker compose run -it --rm web php artisan xboard:update
``` ```
## 4. Start services ## 4. 启动服务
```bash ```bash
docker compose up -d docker compose up -d
``` ```
## 5. Check status ## 5. 检查状态
```bash ```bash
docker compose ps docker compose ps
docs/en/migration/v2board-1.7.3.md
+33 -33
View File
@@ -1,63 +1,63 @@
# V2board 1.7.3 Migration Guide # V2board 1.7.3 迁移指南
This guide explains how to migrate from V2board version 1.7.3 to Xboard. 本指南说明如何从 V2board 1.7.3 版本迁移到 Xboard。
### 1. Database Changes Overview ### 1. 数据库变更概览
- `v2_stat_order` table renamed to `v2_stat`: - `v2_stat_order` 表重命名为 `v2_stat`：
- `order_amount` → `order_total` - `order_amount` -> `order_total`
- `commission_amount` → `commission_total` - `commission_amount` -> `commission_total`
- New fields added: - 新增字段：
- `paid_count` (integer, nullable) - `paid_count`（integer, nullable）
- `paid_total` (integer, nullable) - `paid_total`（integer, nullable）
- `register_count` (integer, nullable) - `register_count`（integer, nullable）
- `invite_count` (integer, nullable) - `invite_count`（integer, nullable）
- `transfer_used_total` (string(32), nullable) - `transfer_used_total`（string(32), nullable）
- New tables added: - 新增数据表：
- `v2_log` - `v2_log`
- `v2_server_hysteria` - `v2_server_hysteria`
- `v2_server_vless` - `v2_server_vless`
### 2. Prerequisites ### 2. 前置条件
⚠️ Please complete the basic Xboard installation first (SQLite not supported): > 注意：请先完成 Xboard 基础安装（不支持 SQLite）：
- [Docker Compose Deployment](../installation/docker-compose.md) - [Docker Compose 部署](../installation/docker-compose.md)
- [aaPanel + Docker Deployment](../installation/aapanel-docker.md) - [aaPanel + Docker 部署](../installation/aapanel-docker.md)
- [aaPanel Deployment](../installation/aapanel.md) - [aaPanel 部署](../installation/aapanel.md)
### 3. Migration Steps ### 3. 迁移步骤
#### Docker Environment #### Docker 环境
```bash ```bash
# 1. Stop services # 1. 停止服务
docker compose down docker compose down
# 2. Clear database # 2. 清空数据库
docker compose run -it --rm web php artisan db:wipe docker compose run -it --rm web php artisan db:wipe
# 3. Import old database (Important) # 3. 导入旧数据库（重要）
# Please manually import the V2board 1.7.3 database # 请手动导入 V2board 1.7.3 数据库
# 4. Execute migration # 4. 执行迁移
docker compose run -it --rm web php artisan migratefromv2b 1.7.3 docker compose run -it --rm web php artisan migratefromv2b 1.7.3
``` ```
#### aaPanel Environment #### aaPanel 环境
```bash ```bash
# 1. Clear database # 1. 清空数据库
php artisan db:wipe php artisan db:wipe
# 2. Import old database (Important) # 2. 导入旧数据库（重要）
# Please manually import the V2board 1.7.3 database # 请手动导入 V2board 1.7.3 数据库
# 3. Execute migration # 3. 执行迁移
php artisan migratefromv2b 1.7.3 php artisan migratefromv2b 1.7.3
``` ```
### 4. Configuration Migration ### 4. 配置迁移
After completing the data migration, you need to migrate the configuration file: 数据迁移完成后，还需要迁移配置文件：
- [Configuration Migration Guide](./config.md) - [配置迁移指南](./config.md)
docs/en/migration/v2board-1.7.4.md
+24 -24
View File
@@ -1,51 +1,51 @@
# V2board 1.7.4 Migration Guide # V2board 1.7.4 迁移指南
This guide explains how to migrate from V2board version 1.7.4 to Xboard. 本指南说明如何从 V2board 1.7.4 版本迁移到 Xboard。
### 1. Database Changes Overview ### 1. 数据库变更概览
- New table added: - 新增数据表：
- `v2_server_vless` - `v2_server_vless`
### 2. Prerequisites ### 2. 前置条件
⚠️ Please complete the basic Xboard installation first (SQLite not supported): > 注意：请先完成 Xboard 基础安装（不支持 SQLite）：
- [Docker Compose Deployment](../installation/docker-compose.md) - [Docker Compose 部署](../installation/docker-compose.md)
- [aaPanel + Docker Deployment](../installation/aapanel-docker.md) - [aaPanel + Docker 部署](../installation/aapanel-docker.md)
- [aaPanel Deployment](../installation/aapanel.md) - [aaPanel 部署](../installation/aapanel.md)
### 3. Migration Steps ### 3. 迁移步骤
#### Docker Environment #### Docker 环境
```bash ```bash
# 1. Stop services # 1. 停止服务
docker compose down docker compose down
# 2. Clear database # 2. 清空数据库
docker compose run -it --rm web php artisan db:wipe docker compose run -it --rm web php artisan db:wipe
# 3. Import old database (Important) # 3. 导入旧数据库（重要）
# Please manually import the V2board 1.7.4 database # 请手动导入 V2board 1.7.4 数据库
# 4. Execute migration # 4. 执行迁移
docker compose run -it --rm web php artisan migratefromv2b 1.7.4 docker compose run -it --rm web php artisan migratefromv2b 1.7.4
``` ```
#### aaPanel Environment #### aaPanel 环境
```bash ```bash
# 1. Clear database # 1. 清空数据库
php artisan db:wipe php artisan db:wipe
# 2. Import old database (Important) # 2. 导入旧数据库（重要）
# Please manually import the V2board 1.7.4 database # 请手动导入 V2board 1.7.4 数据库
# 3. Execute migration # 3. 执行迁移
php artisan migratefromv2b 1.7.4 php artisan migratefromv2b 1.7.4
``` ```
### 4. Configuration Migration ### 4. 配置迁移
After completing the data migration, you need to migrate the configuration file: 数据迁移完成后，还需要迁移配置文件：
- [Configuration Migration Guide](./config.md) - [配置迁移指南](./config.md)
docs/en/migration/v2board-dev.md
+32 -32
View File
@@ -1,61 +1,61 @@
# V2board Dev Migration Guide # V2board Dev 迁移指南
This guide explains how to migrate from V2board Dev version (2023/10/27) to Xboard. 本指南说明如何从 V2board Dev 版本（2023/10/27）迁移到 Xboard。
⚠️ Please upgrade to version 2023/10/27 following the official guide before proceeding with migration. > 注意：迁移前请先按官方指南升级到 2023/10/27 版本。
### 1. Database Changes Overview ### 1. 数据库变更概览
- `v2_order` table: - `v2_order` 表：
- Added `surplus_order_ids` (text, nullable) - Deduction orders - 新增 `surplus_order_ids`（text, nullable）- 扣费订单
- `v2_plan` table: - `v2_plan` 表：
- Removed `daily_unit_price` - Affects period value - 移除 `daily_unit_price` - 影响周期价格
- Removed `transfer_unit_price` - Affects traffic value - 移除 `transfer_unit_price` - 影响流量价格
- `v2_server_hysteria` table: - `v2_server_hysteria` 表：
- Removed `ignore_client_bandwidth` - Affects bandwidth configuration - 移除 `ignore_client_bandwidth` - 影响带宽配置
- Removed `obfs_type` - Affects obfuscation type configuration - 移除 `obfs_type` - 影响混淆类型配置
### 2. Prerequisites ### 2. 前置条件
⚠️ Please complete the basic Xboard installation first (SQLite not supported): > 注意：请先完成 Xboard 基础安装（不支持 SQLite）：
- [Docker Compose Deployment](../installation/docker-compose.md) - [Docker Compose 部署](../installation/docker-compose.md)
- [aaPanel + Docker Deployment](../installation/aapanel-docker.md) - [aaPanel + Docker 部署](../installation/aapanel-docker.md)
- [aaPanel Deployment](../installation/aapanel.md) - [aaPanel 部署](../installation/aapanel.md)
### 3. Migration Steps ### 3. 迁移步骤
#### Docker Environment #### Docker 环境
```bash ```bash
# 1. Stop services # 1. 停止服务
docker compose down docker compose down
# 2. Clear database # 2. 清空数据库
docker compose run -it --rm web php artisan db:wipe docker compose run -it --rm web php artisan db:wipe
# 3. Import old database (Important) # 3. 导入旧数据库（重要）
# Please manually import the V2board Dev database # 请手动导入 V2board Dev 数据库
# 4. Execute migration # 4. 执行迁移
docker compose run -it --rm web php artisan migratefromv2b dev231027 docker compose run -it --rm web php artisan migratefromv2b dev231027
``` ```
#### aaPanel Environment #### aaPanel 环境
```bash ```bash
# 1. Clear database # 1. 清空数据库
php artisan db:wipe php artisan db:wipe
# 2. Import old database (Important) # 2. 导入旧数据库（重要）
# Please manually import the V2board Dev database # 请手动导入 V2board Dev 数据库
# 3. Execute migration # 3. 执行迁移
php artisan migratefromv2b dev231027 php artisan migratefromv2b dev231027
``` ```
### 4. Configuration Migration ### 4. 配置迁移
After completing the data migration, you need to migrate the configuration file: 数据迁移完成后，还需要迁移配置文件：
- [Configuration Migration Guide](./config.md) - [配置迁移指南](./config.md)