使用指南

5 分钟本地启动 · 一键 Docker 部署 · 脚手架脚本创建新项目

快速开始

本地开发环境启动所有端，适合首次体验与二次开发

📋 环境要求

依赖	最低版本	备注
Node.js	≥ 20	管理后台 / Web 端 / 小程序构建
PHP	≥ 8.0	后端 ThinkPHP 8 运行时
MySQL	8.0	数据库
Redis	7.0	缓存（token / 权限 / 设备绑定）
Composer	2.x	PHP 依赖管理

① 克隆仓库

bash

git clone <repo-url> krfclaw-scaffold
cd krfclaw-scaffold

② 后端启动（端口 8080）

bash

cd backend
cp .env.example .env
composer install

# 修改 .env 中的 DB_HOST/DB_PASS/REDIS_HOST/WECHAT_APPID 等
# 导入数据库初始 SQL
mysql -u root -p < ../database/scaffold.sql

# 启动开发服务器（端口 8080）
php think run --port 8080

③ 管理后台启动（端口 5173）

bash

cd admin-frontend
npm install

# 修改 src/config/index.js 中 BASE_URL 指向 http://localhost:8080
npm run dev
# 启动后访问 http://localhost:5173

④ 微信小程序启动

bash

cd wechat-miniprogram
npm install

# 修改 manifest.json 中 mp-weixin.appid 为你的小程序 AppID
npm run dev:mp-weixin

# 用微信开发者工具打开 wechat-miniprogram/dist/dev/mp-weixin

⑤ Web 端启动（端口 3000）

bash

cd web
npm install

# 修改 nuxt.config.ts 中 runtimeConfig.public.apiBase 指向后端
npm run dev
# 启动后访问 http://localhost:3000

首次启动提示：需先导入 database/scaffold.sql 初始化数据库。默认超级管理员手机号 13800000000 / 密码 123456。

Docker 部署

一键编排 · 共享基础设施 · 多项目复用，适合生产环境

① 创建共享网络（首次部署）

bash

# 首次部署需创建共享 Docker 网络
docker network create web-network

② 启动共享基础设施（MySQL + Redis）

bash

cd docker/docker-sites/common
cp .env.example .env

# 修改 .env 中的 MYSQL_ROOT_PASSWORD / REDIS_PASSWORD 等
docker-compose up -d
# 启动 common-mysql (13306) 与 common-redis (16379)

③ 构建前端静态产物

bash

# 构建管理后台静态产物到 admin-frontend/dist
cd admin-frontend && npm install && npm run build && cd ..

# 构建 Web 端静态产物到 web/dist
cd web && npm install && npm run build && cd ..

④ 启动业务容器（Nginx + PHP-FPM）

bash

cd docker
cp .env.example .env

# 修改后端 backend/.env 中：
#   DB_HOST=common-mysql
#   REDIS_HOST=common-redis
docker-compose up -d
# 启动 nginx-api (18113) / nginx-admin (18114) / nginx-web (18115) + php-fpm

端口映射表

端口	服务	容器名	用途
`18113`	nginx-api	scaffold-api-nginx	后端 API
`18114`	nginx-admin	scaffold-admin	管理后台
`18115`	nginx-web	scaffold-web	Web 端
`13306`	common-mysql	-	MySQL（共享）
`16379`	common-redis	-	Redis（共享）

部署提示：业务容器通过容器名访问共享基础设施（如 common-mysql），无需用 IP。修改后端 .env 中 DB_HOST=common-mysql、REDIS_HOST=common-redis。

📄 关键文件

业务编排docker/docker-compose.yml

基础设施docker/docker-sites/common/docker-compose.yml

Nginx 配置docker/nginx/{api,admin,web}.conf

脚手架脚本

一键创建基于本脚手架的新项目，6 步自动完成 + 8 步手动收尾

用法

bash

# 用法
./scripts/create-project.sh <项目名> [项目目录]

# 示例：创建名为 tianju 的新项目
./scripts/create-project.sh tianju /Users/cto/projects/tianju

# 示例：在默认目录创建（/Users/cto/projects/<项目名>）
./scripts/create-project.sh myapp

🤖 六步自动流程

复制脚手架文件（排除 node_modules / vendor / runtime / .git / dist）
配置后端（生成 .env，含 DB/Redis/JWT/微信配置）
配置管理后台（生成 src/config/index.js，含 BASE_URL/SITE_NAME/业务码常量）
配置小程序（更新 manifest.json 的 name/description）
配置 Web 端（替换标题文案）
初始化 Git 仓库并首次提交

📝 八步手动收尾

cd backend && composer install
cd admin-frontend && npm install
cd wechat-miniprogram && npm install
cd web && npm install
修改 backend/.env 中的数据库和微信配置
修改 admin-frontend/src/config/index.js 中的 BASE_URL
修改 wechat-miniprogram/manifest.json 中的 mp-weixin.appid
创建数据库并导入 database/scaffold.sql

⚠️ 安全提示：别忘了修改 .env 中的 JWT_KEY_V1/V2/V3 为随机字符串！默认密钥仅用于开发环境。

📄 关键文件

脚本scripts/create-project.sh