Xboard/docs/development-guide.zh-CN.md

Xboard 开发文档（开发环境 / 本地测试 / 运行 / 编译）

本文面向仓库维护者与二次开发者，覆盖本项目在本地和容器中的完整开发流程。

1. 项目现状与边界

• 后端框架：Laravel 12（laravel/framework）+ Octane（Swoole）+ Horizon。
• 运行依赖：数据库（SQLite / MySQL / PostgreSQL）+ Redis。
• 前端资产：当前仓库已包含编译产物，主要位于：
  • theme/Xboard/assets
  • theme/v2board/assets
  • public/assets/admin
• package.json 仅含 chokidar 依赖，主要用于 Octane --watch 开发体验，不是完整前端工程。

2. 开发环境要求

2.1 必需依赖

• Git
• PHP 8.2+
• Composer 2.x
• Redis 7+
• 数据库三选一：
  • SQLite（最快）
  • MySQL 5.7+
  • PostgreSQL

2.2 推荐依赖（开发体验）

• Docker + Docker Compose（推荐）
• Node.js 18+（仅在使用 php artisan octane:start --watch 时需要）

2.3 操作系统建议

• 推荐 Linux / WSL2。
• compose.sample.yaml 使用 network_mode: host，在非 Linux 环境可能需要改为端口映射（如 7001:7001）。

3. Docker 开发模式（推荐）

3.1 初始化

git clone -b compose --depth 1 https://github.com/cedar2025/Xboard
cd Xboard
cp compose.sample.yaml compose.yaml

3.2 安装（首次）

推荐使用 SQLite + 内置 Redis 的快速安装：

docker compose run -it --rm \
  -e ENABLE_SQLITE=true \
  -e ENABLE_REDIS=true \
  -e ADMIN_ACCOUNT=admin@demo.com \
  web php artisan xboard:install

安装完成后请记录：

• 管理员账号/密码（安装命令输出）
• 后台路径（安装命令输出中的 secure_path）

3.3 启动与停止

docker compose up -d
docker compose ps
docker compose logs -f web
docker compose logs -f horizon

停止：

docker compose down

3.4 访问地址

• 用户前台：http://<host>:7001/
• 管理后台：http://<host>:7001/<secure_path>

说明：secure_path 默认不是固定字符串，而是安装后生成并可在后台配置修改。

4. 宿主机本地开发（非 Docker）

4.1 安装依赖

composer install
cp .env.example .env

如果你计划使用 SQLite，可先准备文件：

mkdir -p .docker/.data
touch .docker/.data/database.sqlite

4.2 首次安装

php artisan xboard:install

安装向导会交互配置：

• 数据库类型（SQLite / MySQL / PostgreSQL）
• Redis 连接（安装阶段会强校验可连通）
• 管理员账号

4.3 启动服务（开发三进程）

建议至少开 3 个终端：

1. Web 服务（Octane）

php artisan octane:start --host=0.0.0.0 --port=7001 --watch

2. 队列消费（Horizon）

php artisan horizon

3. 定时任务（开发态）

php artisan schedule:work

说明：

• 生产环境通常由 cron 调 schedule:run，开发环境直接 schedule:work 更直观。
• 若不使用 --watch，可不安装 Node.js。

4.4 权限问题（Linux）

chmod -R 775 storage bootstrap/cache .docker/.data

5. 本地测试与质量检查

5.1 当前仓库事实

• 当前仓库未包含 tests/ 目录。
• 当前仓库未包含 phpunit.xml / phpunit.xml.dist。

因此默认没有可执行的项目内单元测试套件，建议先补齐测试基建再启用 CI 强校验。

5.2 建议的本地检查基线

php artisan about
php artisan migrate:status
php artisan route:list
vendor/bin/phpstan analyse --memory-limit=1G

如后续补充测试用例后，再执行：

timeout 60s php artisan test

约定：自动化执行测试时，单条任务建议设置 60s 超时，避免阻塞流水线。

6. 运行与调试要点

6.1 调度与队列健康

• 定时任务心跳来源：App\Console\Kernel::schedule 中写入缓存键 SCHEDULE_LAST_CHECK_AT。
• Horizon 状态可在后台系统状态页查看。

若后台提示异常，先检查：

php artisan schedule:list
php artisan horizon:status

6.2 关键日志位置

• 应用日志：storage/logs
• Docker 运行日志：docker compose logs -f web|horizon

7. 编译 / 构建说明

7.1 应用层“编译”边界

• 本仓库不包含完整的后台/前台前端源码工程。
• 默认是消费已编译好的静态资源，不存在常规 npm run build 的全量前端构建链。

7.2 Docker 镜像构建

CI 使用 .github/workflows/docker-publish.yml 进行多架构构建并推送镜像。

本地可执行：

docker build \
  --build-arg CACHEBUST=$(date +%s) \
  --build-arg REPO_URL=https://github.com/cedar2025/Xboard \
  --build-arg BRANCH_NAME=master \
  -t xboard:dev .

重要说明：

• 当前 Dockerfile 在构建时会 git clone 指定仓库分支，不直接打包你本地未提交改动。
• 若目标是“本地改动实时调试”，优先使用 Docker Compose 挂载源码运行，而非用该 Dockerfile 打镜像。

8. 升级、回滚与危险脚本

常用命令：

php artisan xboard:update
php artisan xboard:rollback

注意事项：

• update.sh 包含 git reset --hard origin/master，会覆盖本地改动，不建议在开发分支使用。
• xboard:update / xboard:install 内部包含插件目录恢复逻辑，可能回退 plugins/ 下被 Git 跟踪且非新增的修改。

9. 建议开发流程（最小闭环）

1. 建立分支并完成代码改动。
2. 启动 octane + horizon + schedule:work 做手工联调。
3. 运行静态检查（phpstan）和基础 smoke 检查（about / migrate:status）。
4. 确认后台路径、队列、定时任务均正常后再提交。