本文基于Xboard仓库master 分支当前代码与官方文档撰写，所有命令、Compose 配置、数据库与 Redis 连接方式均以仓库实际内容为准。文中出现的 README / 文档与代码不一致之处，均已单独标注并以实际代码为准。 免责声明：项目 README 明确声明本项目
仅供学习交流使用（educational and learning purposes only）。请遵守当地法律法规，仅在你有权使用的服务器上部署，不要用于任何违法违规用途。
一、Xboard 是什么？
1. Xboard 是什么
Xboard 是一个基于 V2Board 二次开发的高性能面板系统（官方定位：High-performance panel based on V2board secondary development supporting new protocols and new features）。它继承了 V2Board 家族的「面板 + 节点」架构理念，但对底层框架和前端做了全面重构，是目前 V2Board 系列中较现代化的版本。
当前版本的几个显著特点：
底层基于 Laravel 12 + Octane（常驻内存、高性能）；
现代化管理后台（React + Shadcn UI）；
现代化用户前端（Vue 3 + TypeScript）；
Docker 优先的部署方式，一条命令即可初始化、一条命令即可启动；
支持 SQLite / MySQL / PostgreSQL 三种数据库（快速部署默认 SQLite）；
容器内置 Caddy、Redis、WebSocket 服务，开箱即用。
2. 与 V2Board 的关系
Xboard 不是独立重写的产品，而是在 V2Board 基础上二次开发，继承其「用户中心 + 管理后台 + 节点通信 + 订阅下发」的整体设计，同时：
使用全新的技术栈重构前后端与运行架构；
支持更新的协议与特性（配合 Xboard-Node 节点后端）；
官方提供从旧版 V2Board 迁移到 Xboard 的迁移文档（
docs/en/migration/）。
注意：本文只介绍当前版本实际存在的功能，不会把旧版 V2Board 的过期功能直接套用到 Xboard 上。
3. 面板主要负责什么
Xboard 面板是整套系统的「大脑」，负责管理端与用户端两大块：
管理后台（Admin）—— 基于当前代码的实际模块（app/Http/Controllers/V2/Admin）整理：
用户前端（Client）—— 注册 / 登录、购买套餐、查看订阅、下载配置、工单、个人中心等（Vue 3 用户端）。
提示：具体菜单名称与位置可能因面板版本、主题或插件不同而略有差异，请以你当前面板实际界面为准。本文只按当前代码列出功能模块，不逐字编造菜单路径。
4. 核心能力一览
用户管理；
节点管理（支持节点与机器两种形态）；
套餐与订阅；
订单与支付（支付渠道以插件形式安装）；
优惠券 / 礼品卡；
工单 / 公告 / 知识库；
邮件通知；
主题系统与插件系统。
二、当前 Xboard 技术架构
以下内容基于仓库 master 分支的 composer.json、Dockerfile、.docker/ 与前端目录整理。
1. 后端框架
PHP：
^8.2（composer.json 要求）Laravel：
laravel/framework ^12.0→ 当前实际为 Laravel 12Octane：
laravel/octane 2.11.*（常驻内存 HTTP 服务器）
版本差异提示（重要）：master README 开头写的是"built on Laravel 11"，但 README 的 Features 一节写的是"Built with Laravel 12 + Octane"。经核对
composer.json，实际要求laravel/framework ^12.0，因此当前实际版本以 Laravel 12 为准。文中所有内容均按 Laravel 12 描述。
2. 运行方式
Octane 常驻进程提供 HTTP 服务，镜像基于
phpswoole/swoole:php8.2-alpine（内置 Swoole 扩展）；Horizon（
laravel/horizon ^5.30）作为队列管理器（Redis）；WebSocket：
workerman/workerman ^5.1，通过php artisan ws-server start提供面板 ↔ 节点的 WebSocket 同步服务；内置 Caddy：容器内默认启用（
ENABLE_CADDY=true），把 HTTP 与 WebSocket 融合在一个端口上对外提供（详见第九节）。
3. 管理后台与用户前端
管理后台：React + Shadcn UI + TailwindCSS；
用户前端：Vue 3 + TypeScript + NaiveUI。
（以上来自 README Tech Stack 一节，与仓库前端目录结构一致。）
4. Redis 与数据库
Redis：缓存、队列、Session 均由 Redis 支撑（
CACHE_DRIVER=redis、QUEUE_CONNECTION=redis）。Docker 镜像内置 Redis 服务（默认监听 unix socket/data/redis.sock），快速部署时开箱即用；数据库：支持 SQLite / MySQL / PostgreSQL 三种，快速部署默认 SQLite（
.docker/.data/database.sqlite）。
5. Docker / Docker Compose
发布在
ghcr.io/cedar2025/xboard:latest（GitHub Container Registry）；提供 4 套 Compose 模板：
compose.sample.yaml、compose.host.sample.yaml、compose.1panel.sample.yaml、compose.split.sample.yaml；官方文档位置：
docs/en/installation/（docker-compose / 1panel / aapanel / aapanel-docker）。
三、部署前准备
3.1 服务器配置
官方部署文档（宝塔 /aapanel 文档）给出的推荐配置如下：
注意：以上是官方文档的
推荐配置
（适合小规模站点），不是最低配置。实际需求取决于你的用户量与流量规模。
补充：Docker 镜像内置资源档位（
RESOURCE_PROFILE），其中minimal档位内存占用约 250–350 MiB，适合 512 MB 左右的小型 VPS；balanced是默认档位（4 套 Compose 模板默认即balanced）。所以低配 VPS 也可以跑，只是建议按官方推荐配置起步。
3.2 推荐系统
官方文档明确支持的 Linux：
Debian 10+；
Ubuntu 20.04+；
CentOS 7+（宝塔 Docker 文档仍列出；但宝塔原生部署文档明确说 CentOS 7 不推荐）。
新手建议：优先选择 Debian / Ubuntu + Docker 部署。 理由：
Docker 部署与操作系统细节解耦，命令一致；
Debian/Ubuntu 社区资料多、依赖好装；
官方快速安装教程就是基于 Docker。
3.3 域名准备
建议提前准备一个域名（如 panel.example.com），用于后续配置域名与 HTTPS。当然，临时体验也可以先用 http://服务器IP:7001 访问（见第八节）。
DNS 配置：
在 DNS 服务商（如 Cloudflare、阿里云 DNS、DNSPod 等）添加一条 A 记录：
主机记录：
panel（即子域名panel.example.com）记录类型：
A记录值：你的 VPS IPv4 地址
等待 DNS 生效（一般几分钟到几小时），验证：
dig panel.example.com +short
\# 或
nslookup panel.example.com返回你的 VPS IP 即表示 DNS 已生效。
说明：Cloudflare 等只是常见的 DNS/CDN 服务商之一，不是 Xboard 的依赖。你可以用任何 DNS 服务商，Xboard 本身并不要求必须使用 Cloudflare。
四、Xboard 部署方式选择
根据当前仓库实际文档与模板，官方支持的部署方式如下：
说明：以上方式是官方文档（
docs/en/installation/）与仓库 4 套 Compose 模板实际支持的组合。原生宝塔部署不依赖 Docker，但步骤更多；split 模板面向 K8s / 独立伸缩场景。
新手结论：优先 Docker Compose（compose.sample.yaml** 默认模板）。** 全流程最简单，官方文档最完善。
五、Docker Compose 部署【重点】
这是官方最推荐、也最完整的部署方式。以下命令全部来自官方 docker-compose.md 文档。
第 1 步：安装 Docker
官方推荐用官方安装脚本：
curl -sSL https://get.docker.com | bash如果你的系统是 CentOS 等，装完后启动并设置开机自启：
systemctl enable --now docker验证安装：
docker --version
docker compose version说明：
curl -sSL https://get.docker.com | bash是 Docker 官方安装脚本，会自动识别你的系统并安装 Docker Engine + Compose 插件。请确保脚本来源可信（来自官方get.docker.com）。
第 2 步：下载 Xboard
官方当前推荐克隆 compose 分支：
git clone -b compose --depth 1 https://github.com/cedar2025/Xboard
cd Xboard为什么使用 compose 分支？
官方文档明确说明：compose 分支专门为 Docker Compose 部署准备—— 它自带 compose.yaml、compose.host.sample.yaml、compose.1panel.sample.yaml、compose.split.sample.yaml 等 Compose 相关文件，clone 下来即可直接使用，不用再去 master 分支翻找。--depth 1 只拉取最新一次提交，加快下载。
版本差异提示：官方文档的步骤是
cp compose.sample.yaml compose.yaml，但实际上compose分支**已经自带了 **compose.yaml（内容与 master 分支的compose.sample.yaml完全一致），且该分支当前没有compose.sample.yaml这个文件。如果你 clone 的是compose分支，直接使用自带的compose.yaml即可；若想用其它网络模式，再从对应compose.*.sample.yaml复制（见下节）。如果你 clone 的是master分支，则按官方文档执行cp compose.sample.yaml compose.yaml。
第 3 步：创建 Compose 配置
\# 默认模板（bridge 网络，7001 端口映射到宿主机）
cp compose.sample.yaml compose.yaml
\# 如果你用 1Panel，改用：
cp compose.1panel.sample.yaml compose.yaml
\# 如果你用宝塔 + Docker 且偏好 host 网络，改用：
cp compose.host.sample.yaml compose.yaml解释：
compose.sample.yaml是官方提供的「默认部署」模板；compose.yaml是 Docker Compose 默认读取的文件名；为什么要复制一份：
compose.yaml会被 gitignore（见仓库.gitignore），也就是说你对compose.yaml的修改不会污染 git、也不怕git pull覆盖；而compose.*.sample.yaml是模板本身，不要直接改它，否则以后官方更新模板时你无法干净地对比差异。
注意：
compose.sample.yaml的注释明确说明它适合「裸 docker-compose、宝塔 + Docker 管理器、以及走 127.0.0.1:7001 的自定义反向代理（nginx / Caddy / Cloudflare Tunnel 等）」；1Panel 用户要用compose.1panel.sample.yaml（需要加入1panel-network才能连到 1Panel 托管的 MySQL/Redis）；偏好 host 网络的宝塔原生用户用compose.host.sample.yaml。四个模板的详细区别见第十二节。
第 4 步：初始化 Xboard（快速安装）
官方快速安装命令：
docker compose run -it --rm \\
-e ENABLE\_SQLITE=true \\
-e ENABLE\_REDIS=true \\
-e ADMIN\[email protected] \\
xboard php artisan xboard:install这条命令做了什么、每个参数是什么意思：
安装命令实际做了什么（基于 app/Console/Commands/XboardInstall.php 源码）：
检测是否已安装（
.env中INSTALLED为真则提示已安装并退出）；确定数据库类型：
ENABLE_SQLITE=true时直接用 SQLite；否则交互式让你选择 SQLite / MySQL / PostgreSQL；生成
APP_KEY；配置 Redis：Docker 环境下默认使用内置 Redis（写入
REDIS_HOST=/data/redis.sock、REDIS_PORT=0），否则交互式输入地址端口并自动连通性测试；复制
.env.example生成.env；执行数据库迁移（
migrate --force）；注册管理员账号（密码自动生成并打印）；
安装默认插件；
打印安装结果。
安装完成后，请务必保存以下三样东西：
管理后台地址（形如
http://你的域名/一串随机路径，安装结束时会打印，是app.key计算出的安全路径）；管理员账号（邮箱）；
管理员密码（自动生成，安装时打印，只显示一次）。
警告：管理员密码只在安装结束时打印一次，请立即复制保存。如果丢了，可以执行
php artisan reset-password相关命令重置（管理后台也支持修改密码）。
第 5 步：启动 Xboard
docker compose up -d-d 表示后台运行。首次启动会拉取镜像（约几百 MB），需要等待一会儿。
第 6 步：查看状态与日志
docker compose ps看到 xboard 服务状态为 Up 即正常。
docker compose logs -f什么样的日志代表启动正常？
能看到容器启动时自动执行
php artisan xboard:update（迁移 + 插件检查 + 版本缓存 + 主题刷新）的日志；没有反复崩溃、没有
ERROR刷屏；Octane / Horizon / Redis /ws-server/ Caddy 依次启动成功。
说明：
docker compose up -d只是启动，**初始化必须先用第 4 步的 **xboard:install** 完成**。如果直接up -d而不初始化，容器会因为缺少.env/ 数据库而无法正常工作。
六、初始化 Xboard（补充说明）
第一节第 4 步已经执行了初始化。这里补充几个常见疑问：
1. 不传环境变量的交互式安装
如果你想自定义数据库（比如用 MySQL）或 Redis，可以去掉环境变量，交互式安装：
docker compose run -it --rm xboard php artisan xboard:install安装程序会依次问你：数据库类型（SQLite/MySQL/PostgreSQL）→ Redis 地址端口 → 管理员邮箱。此时不会自动用 SQLite，需要手动选。
2. 已经安装过了，再执行会怎样？
会提示「已经安装」，并打印管理后台地址，不会重复安装。
3. 用 SQLite 时数据存在哪？
存在宿主机目录 ./.docker/.data/database.sqlite（Compose 模板把它挂载到了容器内 /www/.docker/.data），这个文件就是你的数据库，备份时一定要备份它。
4. Docker 环境下的 .env 不能删除
源码里有一句：Docker 安装方式下 .env 文件不能删除（只能清空内容），否则安装会报错。.env 通过 Compose 挂载（./.env:/www/.env），删了会导致容器内没有环境文件。
七、启动 Xboard
docker compose up -d
docker compose ps
docker compose logs -fdocker compose ps：查看各服务状态（应为Up）；docker compose logs -f：跟随日志输出（Ctrl+C退出查看，不影响运行）；docker compose restart：重启服务（修改管理员路径等配置后需要重启，见第二十二节）。
八、第一次访问
启动并初始化完成后，浏览器访问：
http://服务器IP:7001默认端口是 7001（Dockerfile
EXPOSE 7001，Compose 映射7001:7001）；首页是用户前端；
管理后台入口是一个随机路径，在初始化时打印（形如
http://服务器IP:7001/xxxxxx，其中xxxxxx是安装时生成的安全路径）。
注意： 如果访问
http://IP:7001打不开，请检查云服务器安全组 / 防火墙是否放行了7001/TCP（详见第二十二节 Q1）； 生产环境不建议长期直接用IP:7001对外访问，建议配置域名 + HTTPS（见第九节）。
九、配置域名和 HTTPS
1. 为什么建议用域名 + HTTPS
用域名可避免 IP 被墙 / 被扫描，也方便以后换服务器；
HTTPS 加密流量，避免用户账号、订阅链接、支付信息被中间人窃听；
浏览器对 HTTP 站点会有「不安全」提示，影响用户体验；
直接用
IP:7001暴露非标准端口，既不美观也不安全。
2. 推荐架构
用户
↓ HTTPS (443)
Nginx / OpenResty（反向代理 + TLS 终结）
↓ http://127.0.0.1:7001
Xboard（内置 Caddy 融合 HTTP + WebSocket）3. 内置 Caddy 的作用（重要）
Docker 镜像内置了 Caddy，默认启用（ENABLE_CADDY=true）。根据仓库 .docker/caddy/Caddyfile：
Caddy 只监听一个公共端口 7001；
把
/ws路径的 WebSocket 请求转发给 ws-server（127.0.0.1:8076）；把其它 HTTP 请求转发给 Octane（
127.0.0.1:7002）；auto_https off，即内置 Caddy 不做 443 HTTPS 终结，只负责 7001 上的 HTTP + WebSocket 融合。
因此：
关键结论
：在 Docker 部署下，面板与节点之间的 WebSocket 已经由内置 Caddy 融合在 7001 端口上。你在外部反向代理（Nginx/OpenResty）里
**不需要再单独配置 **
/ws/** 这个 location**，只要把整个站点反代到127.0.0.1:7001，并用Upgrade/Connection头放行 WebSocket 即可（配置见下）。 （旧版教程里常见的location /ws/ { proxy_pass ...8076 }单独写法，只在非 Docker 原生部署场景才需要，见第十节说明。）
4. Nginx 反向代理配置（官方文档给出的写法）
以 Nginx / OpenResty 为例，server 块内加入：
location ^\~ / {
proxy\_pass http://127.0.0.1:7001;
proxy\_http\_version 1.1;
proxy\_set\_header Host \$http\_host;
proxy\_set\_header X-Real-IP \$remote\_addr;
proxy\_set\_header X-Forwarded-For \$proxy\_add\_x\_forwarded\_for;
proxy\_set\_header Upgrade \$http\_upgrade;
proxy\_set\_header Connection \$http\_connection;
proxy\_read\_timeout 60s;
proxy\_buffering off;
proxy\_cache off;
}每一项的作用：
HTTPS 证书：在 Nginx/OpenResty 上申请并配置 SSL 证书（如 Let's Encrypt 的 certbot，或 1Panel / 宝塔自带的一键 SSL）即可。
十、aaPanel / 宝塔 + Docker 部署
本节根据官方 docs/en/installation/aapanel-docker.md 整理。
10.1 安装宝塔（aaPanel）
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说明：国内宝塔面板（bt.cn）或 aaPanel 国际版都行，按你的环境选择对应安装脚本。安装完成后记下面板地址与默认账号密码。
10.2 安装 Docker
curl -sSL https://get.docker.com | bashCentOS 等系统装完执行：
systemctl enable --now docker10.3 在宝塔中安装依赖软件
进入宝塔面板 → 软件商店，安装：
Nginx（用于反向代理）
MySQL 5.7（用于网站 / 数据库，本部署用于存 Xboard 数据时可选择使用；如果走 SQLite 则可以不装，但官方文档按 MySQL 演示）
不需要安装 PHP 和 Redis（因为用的是 Docker 里的全套环境）
10.4 创建网站
宝塔 → 网站 → 添加站点：
域名：填你的域名（如
panel.example.com）；数据库：MySQL（按提示创建数据库与用户）；
PHP 版本：纯静态（Pure Static）—— 因为我们不用宝塔的 PHP。
10.5 下载 Xboard
cd /www/wwwroot/你的域名目录（宝塔站点目录通常为 /www/wwwroot/panel.example.com）
先清掉宝塔自动生成的默认文件（官方文档给出的命令）：
chattr -i .user.ini
rm -rf .htaccess 404.html 502.html index.html .user.ini然后克隆仓库到当前目录：
git clone -b compose --depth 1 https://github.com/cedar2025/Xboard.git ./10.6 创建 Compose 配置
宝塔 + Docker 场景，官方文档使用 host 网络模板（容器直接用宿主机网络，便于与宝塔的 OpenResty 同机协同）：
cp compose.host.sample.yaml compose.yaml10.7 初始化并启动
docker compose run -it --rm \\
-e ENABLE\_SQLITE=true \\
-e ENABLE\_REDIS=true \\
-e ADMIN\[email protected] \\
xboard php artisan xboard:install
docker compose up -d说明：如果你在宝塔里已经创建了 MySQL 数据库，也可以去掉
ENABLE_SQLITE=true走交互式安装，在提示「选择数据库类型」时选 MySQL，并填入宝塔创建的数据库信息。
10.8 宝塔网站反向代理
在宝塔站点设置 → 反向代理（或直接修改 Nginx 配置文件），把整个站点反代到 127.0.0.1:7001：
location ^\~ / {
proxy\_pass http://127.0.0.1:7001;
proxy\_http\_version 1.1;
proxy\_set\_header Host \$http\_host;
proxy\_set\_header X-Real-IP \$remote\_addr;
proxy\_set\_header X-Forwarded-For \$proxy\_add\_x\_forwarded\_for;
proxy\_set\_header Upgrade \$http\_upgrade;
proxy\_set\_header Connection \$http\_connection;
proxy\_read\_timeout 60s;
proxy\_buffering off;
proxy\_cache off;
}关于 WebSocket（重点解释）：
这一组
Upgrade/Connection头是 WebSocket 反向代理的标准三要素（配合proxy_http_version 1.1）；由于 Xboard 内置 Caddy 已经把 HTTP 与面板↔节点 WebSocket 融合在 7001，所以这里只需要这一组 Upgrade/Connection 即可，不需要再单独加
location /ws/；节点端（Xboard-Node）会自动探测面板的 WebSocket 地址，节点侧无需额外配置。
注意：如果你用的是非 Docker 的原生宝塔部署（见官方aapanel.md，不使用 Compose），那时代理的是 Octane 端口且没有内置 Caddy，才需要单独配置location /ws/ { proxy_pass http://127.0.0.1:8076; ... }。本文（Docker 部署）不需要。
十一、1Panel 部署
本节根据官方 docs/en/installation/1panel.md 整理。
11.1 安装 1Panel
curl -sSL https://resource.fit2cloud.com/1panel/package/quick\_start.sh -o quick\_start.sh
sudo bash quick\_start.sh安装完成后按提示访问 1Panel 面板。
11.2 安装所需软件
在 1Panel「应用商店」安装：
OpenResty（反向代理，创建时建议勾选「外部端口访问」）；
MySQL 5.7（ARM 架构服务器装 MariaDB 替代）。
11.3 创建 MySQL 数据库
1Panel → 数据库 → MySQL → 创建数据库：
数据库名：
xboard用户名：
xboard授权主机：所有主机（
%）密码：自己设置并保存好
11.4 创建网站（反向代理）
1Panel → 网站 → 创建网站 → 反向代理：
域名：
panel.example.com主目录代码：
xboard代理地址：
http://127.0.0.1:7001
之后在网站的 Nginx 配置中加入第九节那组反向代理配置（含 Upgrade/Connection，不需要单独的 /ws/ location）。
11.5 下载 Xboard
进入 1Panel 创建的站点目录：
cd /opt/1panel/apps/openresty/openresty/www/sites/xboard/index安装 git（如未安装）并克隆：
git clone -b compose --depth 1 https://github.com/cedar2025/Xboard.git ./11.6 创建 Compose 配置（1Panel 专用模板）
cp compose.1panel.sample.yaml compose.yaml这个模板和默认模板的区别：额外加入了 1panel-network 这个外部网络（external: true），让 Xboard 容器能通过 1Panel 的 Docker 网络访问到 1Panel 托管的 MySQL。详见第十二节。
11.7 初始化（连接数据库）
docker compose run -it --rm \\
-e ENABLE\_REDIS=true \\
-e ADMIN\[email protected] \\
xboard php artisan xboard:install这里**不要加 **
ENABLE_SQLITE=true（因为 1Panel 场景官方文档演示用 MySQL）。交互式安装时选择MySQL。
数据库连接信息怎么填（重点）：
数据库类型：MySQL
Host（重点）：
如果 Xboard 容器与 MySQL 在同一个 Docker 网络（1Panel 场景下，
1panel-network正是为此加入的），Host 应该用 Docker 服务名 / 容器名，而不是127.0.0.1—— 官方模板注释写明：填 1Panel「数据库 → 连接信息 → Host」中显示的容器名（形如1Panel-mysql-xxxx）；如果连接失败，就去 1Panel 数据库的「连接信息」里看 Container Connection（容器连接） 对应的 Host 值来填；
如果你用的是外部数据库，才填实际的外网地址；
Port：
3306Database：
xboardUsername：
xboardPassword：你在 11.3 设置的密码
Redis：选择内置 Redis（镜像已提供，无需单独配置）
11.8 启动并访问
docker compose up -d然后通过你的域名访问，或临时用 http://服务器IP:7001。
提示：1Panel 文档特别提醒 —— 开启防火墙、只暴露必要端口，避免 7001 裸奔；生产环境建议配置 SSL。
十二、不同 Compose 模板有什么区别
仓库 master 分支（与 compose 分支）一共提供 4 套模板，本文已逐一读取实际 YAML，区别如下：
几个概念解释：
bridge（桥接网络）：容器有自己的网络命名空间，通过
ports把容器端口映射到宿主机。默认、隔离性好，最常用；host（宿主机网络）：容器直接使用宿主机网络栈，性能略好、端口直接用宿主机端口，但隔离性差、端口冲突风险高；
1panel-network：1Panel 创建的共享 Docker 网络，容器加入后可用容器名互相访问，这是 Xboard 访问 1Panel 托管数据库的关键；
split（拆分部署）：一个容器只跑一个角色，可独立重启 / 扩容 / 限流，拓扑为
caddy → web(HTTP :7001) + ws-server(WebSocket :8076)，horizon与redis作为后台服务。
版本差异提示：
compose.split.sample.yaml顶部注释写的是 WebSocket 路径/api/v2/server/ws，但仓库实际的Caddyfile.split中匹配的是path /ws（与默认Caddyfile一致）。以实际运行的 Caddy 配置为准：WebSocket 路径是/ws。
十三、数据库选择
1. 快速部署默认：SQLite
官方快速安装默认使用 SQLite（ENABLE_SQLITE=true），数据库是一个文件：.docker/.data/database.sqlite。
优点：
简单，零配置，不需要单独安装 / 维护 MySQL；
适合快速上手、小规模站点；
备份 = 复制一个文件。
缺点：
不适合所有生产场景；
高并发、规模扩大后需要重新评估（建议迁移到 MySQL）。
注意：SQLite 只是「快速部署默认」，不是官方说「必须用 SQLite」。按你的规模选。
2. MySQL
官方安装命令支持 MySQL（交互式选择，或去掉 ENABLE_SQLITE 后选择）。.env.example 中默认就是 MySQL 的连接项：
DB\_CONNECTION=mysql
DB\_HOST=127.0.0.1
DB\_PORT=3306
DB\_DATABASE=xboard
DB\_USERNAME=root
DB\_PASSWORD=如何准备 MySQL：
安装并启动 MySQL（或使用 1Panel / 宝塔托管的 MySQL）；
创建数据库：
xboard；创建用户并授权（例如用户
xboard、密码自定、允许来自 Xboard 所在主机访问）；在
xboard:install交互式安装时选择 MySQL，依次填入：
Host（同一 Docker 网络用容器名 / 服务名，外部才填 IP 或域名，详见第十一节）；
Port：
3306；Database：
xboard；Username / Password。
说明：仓库文档对 MySQL 版本的描述是宝塔 / 1Panel 文档中的「MySQL 5.7」（1Panel 的 ARM 服务器用 MariaDB），未声明其它更高版本上限。你可以按你面板 / 系统自带的 MySQL 版本安装，只要 Xboard 能连上即可。
3. PostgreSQL
官方安装命令同样支持 PostgreSQL（交互式选择，默认端口 5432、默认库名 xboard、默认用户 postgres）。适合你已经在使用 PostgreSQL 的场景，不是默认选项。
十四、Redis
1. Redis 的作用
Xboard 使用 Redis 作为：
缓存（
CACHE_DRIVER=redis）；队列（
QUEUE_CONNECTION=redis，配合 Laravel Horizon）；Session。
Octane 常驻内存 + Redis 缓存是 Xboard 高性能的重要组成。
2. 快速部署如何启用 Redis
镜像内置 Redis。官方快速安装用 ENABLE_REDIS=true 即表示「使用 Docker 内置 Redis」。安装命令会自动写入：
REDIS\_HOST=/data/redis.sock
REDIS\_PORT=0
REDIS\_PASSWORD=null也就是说，内置 Redis 默认监听 unix socket（/data/redis.sock），不对外开 TCP 端口，既安全又省事。
3. Docker 环境如何连接 Redis
使用内置 Redis：不需要你做任何额外配置（官方推荐，Compose 默认模板的
redis-data:/data数据卷就是给内置 Redis 持久化用的）；使用外部 Redis：去掉
ENABLE_REDIS=true，安装时交互式输入 Redis 地址 / 端口 / 密码，安装程序会自动做连通性测试。
关键结论：Compose 已经自动提供内置 Redis（在镜像里，unix socket 方式），你不需要单独安装 Redis 容器或服务。只有当你明确要用外部 Redis 时才需要自备。
十五、Xboard 后台首次配置
初始化完成后，用管理后台地址（随机安全路径）+ 管理员账号密码登录后台。以下按当前版本实际功能模块给出首次配置建议。
提示：以下仅描述功能区域，具体菜单名称可能因版本 / 主题 / 插件不同而略有差异，请以你当前面板界面为准。
1. 网站基础信息
在「系统配置 / 设置」中填写：
站点名称（前台与后台标题）；
站点描述、Logo、备案信息等；
站点 URL（
APP_URL，务必填你的正式域名，如https://panel.example.com，否则生成的链接可能不对）；管理员路径（secure path）：修改后需要重启容器（见第二十二节 Q6）。
2. 管理员与用户
修改管理员密码（安装时是随机生成的）；
查看用户列表、封禁 / 解封、重置用户流量 / 订阅等。
3. 套餐（Plan）
创建套餐：
名称、价格、周期（月 / 季 / 年等）、流量额度、连接设备数、可用节点组等；
套餐是用户购买订阅的基础，创建后可上架。
4. 节点（Server）
创建节点（见第十六节）；
节点分「普通节点」与「Machine 机器」两种（对应 Xboard-Node 的 node 模式 /machine 模式）。
5. 订阅
节点上线后，为套餐关联节点组；
用户购买套餐后即可获取订阅链接（订阅地址默认形如
你的域名/s/{token}）；订阅地址可在系统配置中自定义前缀（默认
s）。
6. 订单与支付
配置支付渠道（插件式，在「插件」中安装并配置，如 Stripe 等）；
查看订单、处理退款与异常订单。
7. 邮件
配置 SMTP / Mailgun 等邮件服务（
.env中的MAIL_*/MAILGUN_*）；在「邮件模板」中管理发送给用户的邮件内容；
建议配置邮箱验证、找回密码等邮件能力。
8. Telegram / 通知
通知类能力以插件形式提供（官方有
Telegram等插件）。安装对应插件并配置即可；是否支持某通知渠道，以你安装的插件为准，不要假设面板自带。
9. 系统设置
注册开关、邀请 / 推广、强制登录、安全模式（
safe_mode_enable，可限制只能通过指定域名访问）等；备份与更新相关设置（
.env中ENABLE_AUTO_BACKUP_AND_UPDATE等）。
十六、创建节点
1. Node 是什么
在 Xboard 体系里，Node（节点） 是真正提供代理接入的服务器。面板负责管理节点信息（地址、端口、协议、节点组等），节点本身由 Xboard-Node 这个独立程序在节点服务器上运行。
2. 节点与 Xboard-Node 的关系
Xboard（本教程部署的面板）：管理端，负责配置节点、下发用户、统计流量；
Xboard-Node（https://github.com/cedar2025/Xboard-Node）：节点后端，运行在节点服务器上，负责启动 sing-box /xray-core 内核、对外提供代理端口、与面板保持同步。
不要把 Xboard-Node 当成 Xboard 面板本体：
面板是 Xboard，节点后端是 Xboard-Node
，两者部署在两台（或更多）服务器上。
整体架构：
用户
↓ 订阅/登录
Xboard 用户前端（Vue3）
↓
Xboard 面板（Laravel 12 + Octane，管理后台/订阅/订单）
↓ 同步（REST + WebSocket）
Xboard-Node（节点后端）
↓
sing-box / xray-core（代理内核）
↓
节点服务器（对外提供代理端口）3. 在面板创建节点
登录后台 → 节点管理 → 创建节点：
填写节点名称、分组、服务器信息（地址 / 端口 / 协议 / 传输方式等）；
创建成功后，面板会生成一个 Node ID（整数）；
记录该 Node ID，并获取面板的 服务器通信 Token（API Token）。
十七、Xboard 与 Xboard-Node 配合部署
Xboard 与 Xboard-Node 是两个官方配套项目，本节说明如何把它们串起来。
第 1 步：部署 Xboard 面板
按本文第五～九节完成面板部署，并登录后台。
第 2 步：在面板配置节点
后台创建节点，得到 Node ID；同时准备好 API Token（面板节点通信令牌）。
第 3 步：部署 Xboard-Node
在另一台节点服务器上部署 Xboard-Node（Docker 方式示例）：
docker run -d --restart=always --network=host \\
-e apiHost=https://panel.example.com/ \\
-e apiKey=你的API\_TOKEN \\
-e nodeID=节点ID \\
ghcr.io/cedar2025/xboard-node:latest（也可用 systemd Installer 方式，详见 Xboard-Node 官方仓库文档。）
第 4 步：连接面板并查看状态
节点端启动后，回到 Xboard 后台查看该节点是否显示「在线」；
观察节点服务器日志（
docker logs）确认与面板同步成功。
第 5 步：测试用户订阅
给某个用户购买 / 分配一个包含该节点的套餐；
用订阅链接导入客户端，测试能否连接该节点；
面板上该节点开始产生流量数据，即表示面板与节点协同正常。
说明：Xboard-Node 的完整部署教程（Docker / Docker Compose /systemd/xbctl / 配置详解）请参见其官方仓库
https://github.com/cedar2025/Xboard-Node
的文档与示例。本文只说明面板侧如何与它配合。
十八、常用 Docker 管理命令
以下命令在当前 Compose 项目目录下执行（命令与当前 Compose 模板一致）：
提示：
docker compose down会移除容器（默认保留数据卷与.env等挂载文件），不会删除你的数据库和配置；如需连数据卷一起删，才需要docker compose down -v（谨慎使用，见第二十节备份说明）。
十九、Xboard 更新升级
1. 官方当前升级方式
docker compose pull && docker compose up -ddocker compose pull：拉取latest最新镜像；docker compose up -d：用新镜像重建并启动容器。
2. 容器启动时会自动执行 xboard:update
根据官方文档与源码（app/Console/Commands/XboardUpdate.php、entrypoint.sh），容器每次启动（在已安装状态下）会自动执行：
php artisan xboard:update它依次完成：
数据库迁移（
migrate --force）；默认插件安装 / 检查（
PluginManager::installDefaultPlugins）；版本缓存更新（
updateVersionCache）；主题刷新（
refreshCurrentTheme）；如队列非 sync，则重启队列（
horizon:terminate）。
所以正常情况下，docker compose pull && docker compose up -d 之后你无需手动执行迁移。
版本差异提示：官方文档提醒 —— 如果你用的是2026-04-19 之前的
compose.yaml（旧模板），它不会在容器启动时自动跑xboard:update。这类旧模板的升级命令是：
docker compose pull && docker compose run -it --rm web php artisan xboard:update && docker compose up -d建议直接使用当前仓库自带的
compose.yaml，避免这个兼容问题。
3. 原生部署（非 Docker）的升级
原生宝塔部署使用仓库的 update.sh：
git fetch
git reset --hard origin/master
git pull origin master
sh update.sh（update.sh 会更新依赖、同步子模块、执行 php artisan xboard:update 并修正目录权限。）原生方式下，改完还需重启 Octane 常驻进程 / 队列守护。
二十、升级前备份
重要提示：升级 Xboard 前，请先备份数据库。数据库迁移是不可逆的，备份是回滚的底气。
1. SQLite 备份
SQLite 就是复制数据库文件（默认在 .docker/.data/database.sqlite）：
cp .docker/.data/database.sqlite database.sqlite.bak.\$(date +%F)（在 Xboard 项目目录下执行；建议停机或至少停止写入时备份，保证文件一致。）
2. MySQL 备份
mysqldump -h 数据库Host -u xboard -p xboard > xboard\_\$(date +%F).sql（把 Host / 用户名 / 库名替换成你的实际值；1Panel / 宝塔也提供图形化数据库备份。）
3. 配置文件备份
cp .env .env.bak.\$(date +%F).env 里有数据库密码、Redis、邮件、密钥等关键配置。
4. Compose 配置备份
cp compose.yaml compose.yaml.bak.\$(date +%F)5. 顺带建议
备份
./plugins、./storage/theme、./storage/logs等业务数据目录（如需要）；不要把
docker compose down -v、删库等危险命令作为常规升级步骤；升级后观察
docker compose logs确认迁移成功、站点正常，再清理旧备份。
二十一、版本回滚
1. 如何指定 / 回退版本
镜像默认标签是 latest。要固定或回退到某个版本，修改 compose.yaml 中的镜像版本：
services:
xboard:
image: ghcr.io/cedar2025/xboard:<目标版本标签>然后重新启动：
docker compose up -d（up -d 会按新镜像重建容器。）
2. 重要提醒
数据库 migration 可能影响回滚：如果新版本已经执行过数据库迁移并修改了表结构，回退到旧版本镜像后，旧代码可能无法兼容新数据库结构；
不要声称所有版本都可以无损回滚：能否无损回滚取决于该版本是否引入了破坏性的迁移。官方提供了
php artisan xboard:rollback命令（源码XboardRollback.php），说明开发者考虑过回滚场景，但具体能否回滚到某个旧版本，请以该版本 release 说明与你的数据库备份为准；最稳妥的「回滚」= 恢复升级前的数据库备份 + 使用旧版本镜像。
二十二、常见问题排查
Q1：访问 7001 无法打开
按顺序排查：
Docker / 容器：
docker compose ps看xboard是否Up；如果不是，看日志；容器状态：
docker compose logs -f看是否有报错、是否在反复重启；端口：
docker compose ps里看端口映射是否为0.0.0.0:7001->7001/tcp；防火墙：
ufw status/firewall-cmd --list-all是否放行 7001/TCP；云服务器安全组：阿里云 / 腾讯云 / AWS 等控制台的安全组 / 防火墙规则是否放行 7001/TCP；
Nginx：如果用域名访问，检查反向代理配置与证书是否正常；
DNS：域名是否解析到本机 IP、是否生效（见第三节）。
Q2：docker compose up -d 报错
先看日志定位具体服务：
docker compose logs -f常见原因：镜像拉取失败（网络 /ghcr.io 不通）、
compose.yaml语法错误（docker compose config可校验）、./.env文件缺失或异常、端口被占用；确认 Compose 文件与镜像名是否正确（
docker compose config可输出最终解析结果）。
Q3：数据库连接失败
检查：
Host：同一 Docker 网络用容器名 / 服务名（如 1Panel 的
1Panel-mysql-xxxx）；外部数据库才用 IP / 域名；Port：MySQL 默认 3306；
Database：库名是否存在且大小写正确；
Username / Password：授权是否正确（
%或指定主机）；Docker Network：Xboard 容器是否与数据库在同一个网络（1Panel 场景必须用
compose.1panel.sample.yaml加入1panel-network）。
Q4：Redis 连接失败
检查：
Redis 服务：是否用了内置 Redis（
REDIS_HOST=/data/redis.sock、REDIS_PORT=0）；如果手动填了 TCP 地址，确认 Redis 是否真的在监听且密码正确；Docker 网络：外部 Redis 是否可达；
Redis Host / Port / Password：与安装时填写的是否一致（安装时程序会做连通性测试，失败会提示重填）。
Q5：后台空白
主题文件缺失导致前端空白。官方文档给出的恢复方法：
git submodule update --init --recursive --force（源码 init.sh / update.sh / Dockerfile 中也都包含这行，用于同步主题等子模块。）
也可以重建前端静态资源后重启容器；
docker compose restart如果仍然空白，看
docker compose logs是否有「主题加载失败」类错误。
Q6：修改管理员路径后无法访问
官方 README 明确说明：**修改 admin path（管理后台路径）后需要 **docker compose restart。原因：管理后台入口路径在路由注册时读取配置并缓存，改完不重启，旧路径失效、新路径还没生效。修改后执行：
docker compose restartQ7：宝塔部署后访问异常
重点排查：
反向代理：
proxy_pass http://127.0.0.1:7001是否正确、站点是否生效；WebSocket：
Upgrade/Connection头是否已加（内置 Caddy 已融合 WS，不需要/ws/location）；7001：安全组 / 防火墙是否放行；host 网络下端口是否被占用；
OpenResty：Nginx 配置语法（
nginx -t）与重载是否成功；Docker 网络：宝塔场景用
compose.host.sample.yaml（host 网络）时，127.0.0.1:7001才能被宝塔 Nginx 直接访问。
二十三、生产环境安全建议
使用 HTTPS：域名 + 反向代理 + SSL 证书（不要长期裸 HTTP / 裸 IP:7001）；
管理后台不要使用简单密码：安装后立刻修改管理员密码，密码要足够强；
修改默认管理员路径：面板支持自定义后台路径（
secure_path），改成一个不易猜的路径，改后docker compose restart；不公开 .env：
.env含数据库密码、APP_KEY、Redis、邮件等敏感信息，不要提交到公开仓库（仓库.gitignore已忽略.env，请保持）；不公开数据库密码、API Token：不要在博客、截图、聊天中泄露；
开启服务器防火墙，只开放必要端口：面板只需对外暴露 80/443（经反向代理）即可；7001 如无必要可不对外；
定期备份：数据库 +
.env+ Compose 配置（见第二十节）；升级前备份：任何升级前先备份数据库；
不要直接复制网上未知来源的安装脚本：安装脚本要来自官方（
get.docker.com、官方仓库、1Panel / 宝塔官方），并检查内容；定期检查 Docker 镜像版本：关注官方 release，及时
docker compose pull && docker compose up -d。
二十四、完整实战：从 0 部署 Xboard
假设条件：
第一步：SSH 登录服务器
ssh root@你的服务器IP第二步：安装 Docker
curl -sSL https://get.docker.com | bash
systemctl enable --now docker
docker --version第三步：下载 Xboard
git clone -b compose --depth 1 https://github.com/cedar2025/Xboard
cd Xboard第四步：复制 Compose 配置
cp compose.sample.yaml compose.yaml提示：
compose分支已自带与compose.sample.yaml内容一致的compose.yaml，这一步是保险起见确保有一个标准compose.yaml（也可直接用它自带的）。
第五步：执行初始化
docker compose run -it --rm \\
-e ENABLE\_SQLITE=true \\
-e ENABLE\_REDIS=true \\
-e ADMIN\[email protected] \\
xboard php artisan xboard:install第六步：保存管理员账号
务必记录安装结束时打印的：
管理后台地址（
http://你的域名/随机路径）；管理员邮箱；
管理员密码（随机生成，只显示一次）。
第七步：启动容器
docker compose up -d第八步：检查
docker compose psxboard 状态为 Up。
第九步：访问
http://服务器IP:7001看到用户前端首页即成功。
第十步：配置域名
在 DNS 服务商把
panel.example.com解析到服务器 IP（A 记录）；在 Nginx/OpenResty（或 1Panel / 宝塔）创建站点并反代到
127.0.0.1:7001（配置见第九节）。
第十一步：配置 HTTPS
在反向代理层申请并配置 SSL 证书（Let's Encrypt / 面板一键 SSL），使站点通过 https://panel.example.com 访问。
第十二步：登录后台
访问管理后台地址（随机路径），用管理员账号密码登录。
第十三步：进行基础配置
按第十五节完成：站点信息与 URL → 修改管理员密码 → 创建套餐 → 创建节点 → 配置订阅 → 配置支付 / 邮件 → 部署 Xboard-Node 对接节点。
最终架构：
用户
↓ https://panel.example.com（HTTPS）
Nginx / OpenResty（反向代理 + TLS 终结）
↓ http://127.0.0.1:7001
Xboard（内置 Caddy：HTTP + WebSocket 融合）
↓
Redis（内置，unix socket）/ SQLite（数据文件）二十五、Docker Compose 配置文件详解（进阶）
本节以默认模板 compose.sample.yaml 的实际内容逐项解释（只解释实际存在的字段）：
services:
xboard:
image: ghcr.io/cedar2025/xboard:latest
restart: unless-stopped
ports:
- "7001:7001"
volumes:
- ./.env:/www/.env
- ./.docker/.data/:/www/.docker/.data
- ./storage/logs:/www/storage/logs
- ./storage/theme:/www/storage/theme
- ./plugins:/www/plugins
- redis-data:/data
environment:
- RESOURCE\_PROFILE=balanced # minimal | balanced | performance | auto
- ENABLE\_HORIZON=true
- docker=true
volumes:
redis-data:逐项解释：
不存在的字段（不要误解）：
默认模板没有
container_name（容器名由 Compose 自动生成）；默认模板没有
healthcheck（健康检查未配置）；默认模板没有
command（使用镜像内置的entrypoint.sh+supervisord作为入口）；默认模板没有
depends_on（只有拆分部署compose.split.sample.yaml的caddy/web/horizon/ws-server才用到depends_on: redis等）。
host 模板区别： compose.host.sample.yaml 把 ports 换成 network_mode: host（无端口映射，直接用宿主机网络与端口）。
1Panel 模板区别： compose.1panel.sample.yaml 在 ports 基础上增加 networks（default + 外部网络 1panel-network，external: true）。
split 模板区别： compose.split.sample.yaml 拆成 caddy / web / horizon / ws-server / redis 五个服务，通过 ENABLE_CADDY=false、ENABLE_WEB=false 等环境变量按角色关掉不必要的进程（详见第十二节）。
二十六、Docker 与 1Panel / 宝塔怎么选？
推荐 Docker Compose：
适合希望自己控制服务器、配置清晰、方便迁移的用户；
官方默认教程、最完善、升级最省心（一条
docker compose pull && docker compose up -d）。
推荐 1Panel：
适合喜欢图形化服务器管理的人；
数据库 / 网站 / 证书都用 1Panel 图形化创建，配合
compose.1panel.sample.yaml一步到位。
推荐宝塔 + Docker：
适合已经习惯宝塔的网站运维用户；
用
compose.host.sample.yaml或compose.sample.yaml+ 宝塔反向代理即可。
明确建议：如果只是第一次部署 Xboard，优先推荐Docker Compose（
compose.sample.yaml默认模板）。简单、可控、易维护。
二十七、总结
Xboard 是什么：基于 V2Board 二次开发的高性能面板，Laravel 12 + Octane，现代化前后端，负责节点 / 用户 / 套餐 / 订阅 / 订单 / 支付等管理；
推荐部署方式：Docker Compose（默认模板）最推荐；1Panel 用户用
compose.1panel.sample.yaml；宝塔用户用compose.host.sample.yaml+ 反向代理；Docker Compose 怎么部署：装 Docker → clone
compose分支 →compose.yaml→xboard:install初始化 →docker compose up -d；1Panel 怎么部署：装 1Panel → 商店装 OpenResty + MySQL → 建库建站 → clone →
compose.1panel.sample.yaml→ 安装时填 1Panel 容器网络内的数据库 Host →docker compose up -d；宝塔怎么部署：装宝塔 → 装 Nginx + MySQL → 建站 → clone →
compose.host.sample.yaml→ 初始化 → 启动 → 站点反向代理到127.0.0.1:7001；如何配置域名：DNS 加 A 记录指向 VPS IP，反向代理到 7001；
如何配置 HTTPS：在反向代理层（Nginx/OpenResty/1Panel / 宝塔）配置 SSL 证书；
如何升级：
docker compose pull && docker compose up -d（容器启动自动执行xboard:update）；原生部署用sh update.sh；出问题优先查看哪里：先
docker compose ps看状态，再docker compose logs -f看日志，然后按第二十二节逐项排查（端口、防火墙、安全组、数据库连接、Redis、WebSocket）。
本文基于 Xboard 仓库 master 分支（含 compose 分支配套文件）当前代码与官方文档整理，命令与配置请以你部署时仓库的实际版本为准。若 README 与代码不一致，以实际可运行代码为准。
Xboard 部署教程：Docker Compose、1Panel、宝塔完整安装指南
https://blog.aig.onl/archives/xboard
评论