Chapel 是一个三端婚礼管理项目：Spring Boot 后端、Vue 管理后台、uni-app 移动端。当前部署方式统一为 Docker Compose 全栈启动：MySQL 8、后端、前端一起运行；本地源码开发则推荐只用 Docker 启动 MySQL，前后端在本机热调试。
.
├── chapel-backend/ # Spring Boot 3.2.5 + Java 21 + MyBatis Plus + Flyway
├── chapel-frontend/ # Vue 3 + TypeScript + Vite + TDesign + Pinia
├── docker-compose.yml # MySQL 8 + backend + frontend
└── .env.example # Docker / 后端运行环境变量示例
当前开源范围只包含 chapel-backend 和 chapel-frontend。chapel-mobile/、design/、icon/ 暂不纳入根仓库；后续移动端开发完成或需要公开设计资源时，再移除根 .gitignore 中对应忽略规则并纳入统一仓库。
根目录是唯一 Git 仓库；后端和前端不再单独维护 .git。
Docker 命名约定：
- Compose project 固定为
chapel。 - 容器名统一使用
chapel-模块名，例如chapel-mysql、chapel-backend、chapel-frontend。 - 后续如果增加 Redis、任务队列、对象存储模拟器等模块，建议继续使用
chapel-redis、chapel-worker这类命名。 - Compose service 名可以保持简短，例如
mysql、backend、frontend，方便服务之间引用。 - 自研应用镜像使用
chapel-模块名:${APP_IMAGE_TAG:-latest}；第三方基础服务镜像保持官方名，例如mysql:8.0、redis:7-alpine。 - 所有 Chapel 服务都加统一 label：
com.chapel.project=chapel，便于 Docker / OrbStack 中过滤。
新增 Docker 模块时按这个模板：
services:
redis:
image: redis:7-alpine
container_name: chapel-redis
labels:
com.chapel.project: chapel
networks:
- chapel-net
worker:
image: chapel-worker:${APP_IMAGE_TAG:-latest}
build:
context: ./chapel-worker
dockerfile: Dockerfile
container_name: chapel-worker
labels:
com.chapel.project: chapel
depends_on:
- backend
networks:
- chapel-net| 模块 | 技术栈 | 常用端口 |
|---|---|---|
| 后端 | Spring Boot 3.2.5、Java 21、MyBatis Plus、Flyway、JWT | 8080 |
| 前端 | Vue 3、TypeScript、Vite、TDesign、Pinia | 3002 开发 / 80 容器 |
| 移动端 | uni-app、Vue、微信小程序/H5 | 由 uni-app 命令决定 |
| 数据库 | MySQL 8.0 | 3306 |
- 数据库表统一使用
chapel_前缀。 - 主键使用 ULID 字符串，实体使用
@TableId(type = IdType.ASSIGN_UUID)，不要改成ASSIGN_ID。 - 数据删除是物理删除，不使用
@TableLogic，也不新增deleted字段。 - 婚礼数据隔离由后端
WeddingDataInterceptor在 MyBatis 层处理。新增业务表时要确认是否需要加入拦截白名单。 - 后端只保留一份
application.yml，不再使用application-dev.yml/application-prod.yml。本地、Docker、生产差异都通过.env或环境变量控制。 - OSS 不写进代码和示例文件。开发环境使用
chapel-dev桶，生产环境使用chapel-prod桶，真实 AK/SK 只放在本机或服务器.env。 doc/note.md是个人笔记，维护文档时不要修改。
首次准备：
cp .env.example .env.env 已被 .gitignore 忽略，不要提交。常用变量：
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=chapel
MYSQL_USER=chapel
MYSQL_PASSWORD=chapel
MYSQL_PORT=3306
MYSQL_DATA_DIR=./.docker/mysql/data
BACKEND_PORT=8080
BACKEND_LOG_DIR=./.docker/backend/logs
JWT_SECRET=本地或生产随机字符串
JAVA_OPTS=-Xms256m -Xmx512m
FRONTEND_PORT=80
OSS_ENDPOINT=https://oss-cn-shanghai.aliyuncs.com
OSS_ACCESS_KEY_ID=开发或生产真实值
OSS_ACCESS_KEY_SECRET=开发或生产真实值
OSS_BUCKET_NAME=chapel-dev
OSS_URL_PREFIX=https://chapel-dev.oss-cn-shanghai.aliyuncs.com生产环境把 OSS 改成生产桶：
OSS_BUCKET_NAME=chapel-prod
OSS_URL_PREFIX=https://chapel-prod.oss-cn-shanghai.aliyuncs.com适合验证容器镜像、nginx 代理、环境变量、MySQL 挂载是否正确。
cp .env.example .env
docker compose up -d --build
docker compose ps默认访问：
http://localhost
如果本机 80 或 3306 被占用，修改 .env：
FRONTEND_PORT=3000
MYSQL_PORT=3307然后访问：
http://localhost:3000
查看日志：
docker compose logs -f mysql
docker compose logs -f backend
docker compose logs -f frontend代码修改后，容器调试不会热更新，需要重建对应镜像：
docker compose up -d --build frontend # 只改前端
docker compose up -d --build backend # 只改后端
docker compose up -d --build # 前后端都改停止但保留数据库：
docker compose down删除本地 MySQL 数据：
docker compose down
rm -rf .docker/mysql/data日常开发推荐这种方式：MySQL 用 Docker，后端和前端在本机跑。
前置要求：
- JDK 21。项目不能用 JDK 11 编译。
- Maven。可以直接使用默认本地仓库；如果你本机有独立 Maven 仓库，可以通过
-Dmaven.repo.local=/path/to/maven_repository指定。 - Node.js 20.19+。
- npm。
- 根目录
.env已填入开发 OSS 的 AK/SK。
先启动 MySQL：
docker compose up -d mysql
docker compose ps mysqlfish 加载 .env 并启动后端：
cd chapel
for line in (grep -v '^#' .env | grep -v '^$')
set kv (string split -m1 '=' $line)
set -gx $kv[1] $kv[2]
end
cd chapel-backend
set -gx MYSQL_HOST 127.0.0.1
mvn -Dmaven.repo.local=/path/to/maven_repository spring-boot:run如果不需要指定独立 Maven 仓库，可以直接运行：
mvn spring-boot:runzsh/bash 加载 .env 并启动后端：
cd chapel
set -a
source .env
set +a
cd chapel-backend
MYSQL_HOST=127.0.0.1 mvn -Dmaven.repo.local=/path/to/maven_repository spring-boot:run如果不需要指定独立 Maven 仓库，可以直接运行：
MYSQL_HOST=127.0.0.1 mvn spring-boot:run启动前端：
cd chapel/chapel-frontend
npm install
npm run dev前端地址：
http://localhost:3002
Vite 会把 /api 和 /auth 代理到 http://127.0.0.1:8080。
注意：
- 如果后端提示 OSS 配置为空，先确认当前 shell 已加载根目录
.env。 - 如果前端接口 502，先确认后端是否在
127.0.0.1:8080。 - 如果改了
.env，已经启动的后端不会自动感知，需要重新加载环境变量并重启。 - 如果
.env把MYSQL_PORT改成3307，本机源码后端也要使用MYSQL_PORT=3307。
生产环境 HTTPS 建议由宿主机 nginx、宝塔 nginx、Caddy、Traefik 或云负载均衡这类边缘入口处理。Compose 只启动应用容器，不维护容器内 SSL。
生产链路：
浏览器 HTTPS
-> 宿主机 nginx / edge proxy
-> 127.0.0.1:81 前端容器
-> chapel-backend:8080 后端容器
-> chapel-mysql:3306 MySQL 8 容器
生产 .env 关键值：
MYSQL_ROOT_PASSWORD=生产_root_密码
MYSQL_DATABASE=chapel
MYSQL_USER=chapel
MYSQL_PASSWORD=生产_chapel_密码
MYSQL_PORT=127.0.0.1:3306
MYSQL_DATA_DIR=./.docker/mysql/data
BACKEND_PORT=127.0.0.1:8080
BACKEND_LOG_DIR=./.docker/backend/logs
LOG_LEVEL=info
SPRING_LOG_LEVEL=warn
MYBATIS_LOG_LEVEL=warn
ROOT_LOG_LEVEL=warn
JWT_SECRET=使用_openssl_rand_base64_32_生成的随机字符串
JAVA_OPTS=-Xms512m -Xmx1024m
FRONTEND_PORT=127.0.0.1:81
OSS_ENDPOINT=https://oss-cn-shanghai.aliyuncs.com
OSS_ACCESS_KEY_ID=真实值
OSS_ACCESS_KEY_SECRET=真实值
OSS_BUCKET_NAME=chapel-prod
OSS_URL_PREFIX=https://chapel-prod.oss-cn-shanghai.aliyuncs.com部署：
docker compose up -d --build
docker compose ps
docker compose logs -f backend旧生产环境已经有 mysql_8 时，推荐用 mysqldump 迁移，不要直接搬数据目录。
先备份旧库：
docker ps
docker exec -it mysql_8 mysql -u chapel -p -e "SELECT VERSION();"
docker exec mysql_8 mysqldump \
-u chapel \
-p \
--single-transaction \
--routines \
--triggers \
--events \
--default-character-set=utf8mb4 \
chapel > chapel_backup.sql
gzip -k chapel_backup.sql新环境先启动 MySQL：
docker compose up -d mysql
docker compose logs -f mysql
docker compose ps mysql导入数据：
docker exec -i chapel-mysql mysql \
-u chapel \
-p \
--default-character-set=utf8mb4 \
chapel < chapel_backup.sql如果是压缩备份：
gunzip -c chapel_backup.sql.gz | docker exec -i chapel-mysql mysql \
-u chapel \
-p \
--default-character-set=utf8mb4 \
chapel检查表：
docker exec chapel-mysql mysql -u chapel -p chapel -e "SHOW TABLES;"确认数据后再启动完整服务：
docker compose up -d --build如果生产环境已有宿主机 nginx 配置，可以继续使用。关键是生产 .env 要把容器端口绑定到本机回环地址，并和代理端口一致：
FRONTEND_PORT=127.0.0.1:81
BACKEND_PORT=127.0.0.1:8080下面以 your-domain.com 为例，宿主机 nginx 代理可以这样写：
server {
listen 443 ssl;
server_name your-domain.com www.your-domain.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location /auth/ {
proxy_pass http://127.0.0.1:8080/auth/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/ {
proxy_pass http://127.0.0.1:8080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location / {
proxy_pass http://127.0.0.1:81;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}建议在 443 的 server 块增加：
client_max_body_size 50m;
proxy_connect_timeout 30s;
proxy_send_timeout 120s;
proxy_read_timeout 120s;验证并重载：
nginx -t
nginx -s reload如果使用宝塔管理 nginx，优先用宝塔面板重载。
常用命令：
docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f mysql
docker compose restart backend
docker compose up -d --build backend
docker compose down数据库备份：
docker exec chapel-mysql mysqldump \
-u chapel \
-p \
--single-transaction \
--routines \
--triggers \
--events \
--default-character-set=utf8mb4 \
chapel | gzip > "chapel_backup_$(date +%Y%m%d_%H%M%S).sql.gz"升级或发布：
git pull
docker compose up -d --build
docker compose logs -f backend新增一个业务模块通常涉及三端：
- 后端：
entity/、mapper/、service/、controller/，必要时新增 Flyway 迁移。 - 前端：
src/api/、src/store/modules/、src/pages/、src/router/modules/chapel.ts。 - 移动端：
src/api/、src/store/、src/pages/、src/pages.json。
后端维护注意：
- 新表使用
chapel_前缀。 - 新表主键使用
CHAR(26)ULID。 - 已执行的 Flyway 文件不要修改，新增结构变更时添加
V3__xxx.sql这类新迁移。 - 需要婚礼隔离的查询要确认
WeddingDataInterceptor是否覆盖。 - 用户可见错误、日志、Javadoc 尽量保持中文。
前端维护注意：
- 业务接口路径已经显式写
/api/...，调用时沿用现有isJoinPrefix: false模式。 /auth/...不带/api前缀。- 路由标题使用
{ zh_CN, en_US }，不要改成纯字符串。 - 主题色和自定义变量集中在
src/style/chapel-theme.less。
后端无法连接 MySQL：
docker compose ps mysql
docker compose logs -f mysql
docker compose logs -f backend确认容器内后端使用 MYSQL_HOST=mysql，本机源码后端使用 MYSQL_HOST=127.0.0.1。
前端登录失败：
- 检查 nginx 是否代理
/auth/。 - 检查后端是否在
8080。 - 检查浏览器请求是否打到正确域名和端口。
OSS 上传失败：
- 检查当前
.env是否有OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。 - 本地确认桶是
chapel-dev，生产确认桶是chapel-prod。 - 修改
.env后要重启后端。
Maven 编译提示“不支持发行版本 21”：
- 当前 JDK 不是 21。
- 切换到 JDK 21 后重跑 Maven。
Docker 构建失败：
- 确认 Docker / OrbStack 已启动。
- 重新运行
docker compose up -d --build。