Files

T

peanut 5b31845b33 docs：新增本地服务管理规则优化设计文档

- 强制使用 dev-services.py 控制本地服务
- 前端/H5 固定端口从 5178 开始累加
- 优化 restart 命令，避免无意义重启

2026-06-28 10:16:29 +08:00

5.8 KiB

Raw Blame History

author, created_at, purpose

author	created_at	purpose
claude	2026-06-27	规范本地服务管理：强制使用 dev-services.py 控制前后端服务，固定前端/H5 端口从 5178 开始累加，优化热加载避免无意义重启

本地服务管理规则优化设计

背景

当前项目使用 dev-services.py 管理本地前后端服务，但存在以下问题：

前端/H5 端口分散配置在各自 vite.config.* 中，未统一管理
dev-services.py 端口冲突时自动递增，导致端口号不稳定
用户已习惯使用 dev-services.py，但缺少"禁止无意义重启"的强制约束
热加载场景下，开发者可能误重启支持热更新的前端服务，浪费时间

目标

强制：启动/重启/停止本地前后端服务必须使用 dev-services.py
固定：前端和 H5 服务端口从 5178 开始累加分配
优化：dev-services.py restart 在无必须重启的变更时禁止重启
一致：更新 CLAUDE.md 规则文档，与脚本行为对齐

方案选择

采用 方案 A：dev-services.py 内置固定端口表 + 修改各项目 vite 配置

端口控制集中且与项目配置一致
与现有 dev-services.py 架构兼容
便于开发者直接查看配置文件了解端口

详细设计

1. 固定端口分配表

服务	目录	类型	固定端口
Emotion-museum-web	`web/`	Vite	5178
Emotion-museum-admin	`web-admin/`	Vite	5179
Emotion-museum-uniapp	`mini-program/`	UniApp H5	5180
Life-script 前端	`life-script/`	Vite	5181

后端服务端口保持现有配置不变。

2. dev-services.py 修改

2.1 新增固定端口映射

FIXED_FRONTEND_PORTS = {
    "web": 5178,
    "web-admin": 5179,
    "mini-program": 5180,
    "life-script": 5181,
}

按项目目录名匹配。如果目录名不在映射中，仍按原有逻辑处理。

2.2 修改端口分配逻辑

在 assign_unique_ports() 中：

对 FIXED_FRONTEND_PORTS 中定义的服务，强制使用固定端口
如果固定端口被非前端服务占用，报错退出
如果固定端口被另一个前端服务占用，报错退出（说明映射配置错误）
不再对前端服务自动递增端口

2.3 新增 restart 热加载保护

定义"必须重启才能生效"的文件模式：

RESTART_REQUIRED_PATTERNS = [
    r'vite\.config\.(ts|js|mjs|cjs)$',
    r'tsconfig\.json$',
    r'\.env(\.[^/]*)?$',
    r'package\.json$',
    r'application.*\.ya?ml$',
    r'pom\.xml$',
    r'build\.gradle(\.kts)?$',
]

restart 命令执行前：

获取 git 工作区中已修改的文件列表：git diff --name-only
如果没有修改，提示"未检测到代码变更，无需重启"
如果修改文件匹配 RESTART_REQUIRED_PATTERNS，允许正常 restart
如果修改文件不匹配，拒绝 restart 并提示：

当前修改只涉及支持热加载的源码文件，无需重启。如需强制重启，请使用 python dev-services.py restart --force

2.4 支持 `--force` 参数

在 restart 子命令解析中增加 --force 选项，允许用户绕过热加载保护强制重启。

3. 前端项目配置修改

文件	修改内容
`web/vite.config.ts`	`server.port` 改为 5178
`web/.env.development`	添加 `VITE_PORT=5178`
`web-admin/vite.config.ts`	`server.port` 改为 5179
`web-admin/.env.development`	`VITE_APP_PORT` 改为 5179
`mini-program/vite.config.js`	`server.port` 改为 5180
`mini-program/.env.development`	添加 `VITE_PORT=5180`
`life-script/vite.config.js`	`server.port` 改为 5181
`life-script/.env.development`	添加 `VITE_PORT=5181`（不存在则创建）

4. CLAUDE.md 规则更新

新增"本地服务管理规则"章节：

必须使用 dev-services.py：
- 启动、重启、停止本地前后端服务必须使用 python dev-services.py [命令] [服务名]
- 禁止直接使用 npm run dev、npm run dev:h5、mvn spring-boot:run 等命令
前端/H5 固定端口：
- web: 5178
- web-admin: 5179
- mini-program: 5180
- life-script: 5181
禁止无意义重启：
- 只有修改必须重启才能生效的文件时，才允许执行 restart
- 修改源码文件（.vue、.tsx、.ts、.js、.css、.scss 等）时禁止 restart
- 确需强制重启时，使用 python dev-services.py restart --force
热加载规则：
- 前端修改源码文件优先利用热加载
- 后端修改代码按现有规则处理（本地不启动后端，使用服务器验收）

5. 边界情况

场景	行为
固定端口被占用	`dev-services.py` 报错，要求先停止占用该端口的服务
无代码变更执行 restart	提示无需重启
只修改 `.vue` 文件执行 restart	拒绝重启，提示使用 `--force` 或无需重启
修改 `vite.config.ts` 执行 restart	允许正常 restart
多个服务同时 restart	每个服务独立检测，符合规则的重启，不符合的跳过
用户传 `--force`	跳过所有检测，强制重启

修改范围

文件	操作
`dev-services.py`	修改：添加固定端口映射、优化端口分配、新增热加载保护
`web/vite.config.ts`	修改：端口改为 5178
`web/.env.development`	修改/创建：添加 `VITE_PORT=5178`
`web-admin/vite.config.ts`	修改：端口改为 5179
`web-admin/.env.development`	修改：`VITE_APP_PORT` 改为 5179
`mini-program/vite.config.js`	修改：端口改为 5180
`mini-program/.env.development`	修改/创建：添加 `VITE_PORT=5180`
`life-script/vite.config.js`	修改：端口改为 5181
`life-script/.env.development`	修改/创建：添加 `VITE_PORT=5181`
`CLAUDE.md`	修改：更新本地服务管理规则

5.8 KiB Raw Blame History Unescape Escape