启动指南

环境要求

• PHP 8.3+
• Composer
• MySQL 8
• Redis
• Node.js 20.19+（frontend-admin-v3 与 frontend-user-v4-console 的 package 约束）

本地联调统一使用 127.0.0.1，不要混用 localhost。

后端

cd backend
composer install
php artisan key:generate
php artisan migrate
php artisan app:serve

缓存与 Redis 配置

本地开发默认 CACHE_STORE=file（.env 中配置），单进程运行时足够。

生产环境必须设置 CACHE_STORE=redis：

• 分布式锁（Cache::lock）在 file 驱动下不支持跨进程互斥
• 支付回调、订单创建、返利计算等关键业务依赖 Redis 锁保证幂等
• Redis 不可用时这些操作可能并发冲突导致数据错误

检查 Redis 是否运行：

redis-cli ping  # 应返回 PONG

php artisan app:serve 是本项目本地后端统一入口，会拉起 Laravel HTTP、VNC Relay 和业务队列 Worker。不要用 php artisan serve 替代。

需要本地同时带调度时，建议让 Relay 独立运行：

cd backend
php artisan app:serve --with-schedule --without-vnc
php artisan vnc:relay

带调度时，app:serve --with-schedule --without-vnc 不再另起业务队列 Worker；每分钟心跳会并行消费业务队列与 automation 队列，并为两类 Worker 分别加锁。Relay 单独进程退出不会影响 HTTP 和调度入口。

生产环境不使用 app:serve 常驻，PHP-FPM 指向 backend/public，宝塔每分钟执行：

cd backend
php artisan schedule:run

前端

推荐在仓库根目录使用 pnpm workspace 脚本：

pnpm run dev:admin-v3
pnpm run dev:user-v3-www
pnpm run dev:user-v4-console
pnpm run dev:docs

也可以进入子项目：

cd frontend-admin-v3
pnpm run dev

cd frontend-user-v3-www
pnpm run dev

cd frontend-user-v4-console
pnpm run dev

当前真实前端目录：

• frontend-admin-v3：管理端，TDesign Vue Next，默认端口以 Vite 配置为准。
• frontend-user-v3-www：官网与用户入口，Element Plus。
• frontend-user-v4-console：新版用户控制台，TDesign Vue Next。
• shared：跨端共享包。
• docs-web：独立 VitePress 官方文档站，内容直接读取 docs/。

构建与验证

# 全部当前前端
pnpm run build:frontends
pnpm run typecheck:frontends
pnpm run test:frontends
pnpm run verify:frontends

# 单项目
pnpm run build:admin-v3
pnpm run build:user-v3-www
pnpm run build:user-v4-console
pnpm run build:docs
pnpm run docs:check

后端验证：

cd backend
php artisan test

文档或配置类改动至少自检内容是否与当前目录、脚本和代码一致。

数据库初始化与迁移

初始化新库和旧库迁移属于高影响操作，不由代理自动执行：

python backend/scripts/install_db.py
python backend/scripts/migrate_legacy_dump.py --dump "你的dump文件.sql" --dry-run
python backend/scripts/migrate_legacy_dump.py --dump "你的dump文件.sql"

执行前必须确认目标库、备份和 .env。