docs: 添加 README.md,记录正确的启动方式和端口规范

- 重要发现:服务被 OpenClaw 杀掉(SIGTERM)
- 解决方案:使用 nohup + disown 脱离进程树
- 更新所有项目的 start_cmd 为正确的启动方式
- 记录端口规范(19000-19100)
- 记录故障排查步骤
This commit is contained in:
2026-04-15 09:59:39 +08:00
parent cc18d254a8
commit 70eab1f1b8
2 changed files with 155 additions and 11 deletions

131
README.md Normal file
View File

@@ -0,0 +1,131 @@
# 项目服务管理面板
统一管理所有 Web 服务项目,提供状态检测、启动/停止控制、日志查看等功能。
## 端口
- **服务端口**: 19013
- **访问地址**: http://localhost:19013
## 功能
- 项目列表展示(状态、端口、版本)
- 服务状态健康检测
- 启动/停止/重启控制
- 日志查看(实时滚动)
- Git 仓库链接
## 启动方式 ⭐
**重要:必须使用 `nohup + disown` 方式启动,脱离进程树!**
```bash
cd ~/.openclaw/workspace-coder/works/project-panel
nohup python3 app.py > logs/app.log 2>&1 & disown
```
### 为什么需要 disown
如果通过 OpenClaw 的 exec 启动服务,当 OpenClaw 清理进程时(如超时、重启),会发送 SIGTERM 杀掉所有子进程。
使用 `nohup + disown` 可以:
1. `nohup` - 让进程忽略 SIGHUP终端关闭信号
2. `disown` - 从 shell 进程树中移除,避免被连带杀掉
3. `> logs/app.log 2>&1` - 重定向输出到日志文件
### ❌ 错误方式
```bash
# 不要用这种方式(会被 OpenClaw 杀掉)
python3 app.py
```
### ✅ 正确方式
```bash
nohup python3 app.py > logs/app.log 2>&1 & disown
```
## 项目配置
项目配置在 `projects.json` 中,每个项目包含:
```json
{
"id": "project-id",
"name": "项目名称",
"ports": [19000],
"directory": "works/project-dir",
"start_cmd": "nohup python3 app.py > logs/app.log 2>&1 & disown",
"health_url": "http://localhost:19000/api/health",
"admin_url": "http://localhost:19000/admin",
"git_repo": "http://192.168.2.8:12007/coder/project",
"version": "v1.0.0"
}
```
## 端口规范
所有 Web 服务必须使用 **19000-19100** 端口范围:
| 端口 | 项目 |
|------|------|
| 19000 | PDF翻译助手 V2 |
| 19001 | LLM Index RAG |
| 19009 | 碎片信息记录 |
| 19010 | ParamHub Python |
| 19013 | 项目服务管理面板(本服务) |
| 19014 | Xian Favor 收藏系统 |
| 19020 | AI对话系统 |
| 19007 | LLM Proxy |
| 19011 | 产品参数爬取系统 |
| 19004 | 技术论坛 |
| 19015 | 多智能体竞标调度系统 |
## API 接口
- `GET /api/projects` - 获取所有项目列表
- `GET /api/project/:id` - 获取单个项目详情
- `POST /api/project/:id/start` - 启动项目
- `POST /api/project/:id/stop` - 停止项目
- `POST /api/project/:id/restart` - 重启项目
- `GET /api/project/:id/logs` - 获取项目日志
## 监控
服务监控由 `service-monitor` 负责,每 20 分钟检查一次,发送邮件通知。
## 故障排查
### 服务频繁停止?
检查是否使用了正确的启动方式:
1. 确认使用了 `nohup + disown`
2. 确认日志目录存在:`mkdir -p logs/`
3. 查看日志:`cat logs/app.log`
### OpenClaw 杀进程?
如果日志突然停止(约凌晨 01:10可能是被 OpenClaw 清理进程杀掉了。
**证据:**
- OpenClaw 日志:`[tools] exec failed: Command aborted by signal SIGTERM`
- 服务日志最后记录时间01:09 左右
**解决:** 使用 `disown` 脱离进程树。
## Git 仓库
http://192.168.2.8:12007/coder/project-panel
## 更新日志
### v1.0.1
- 添加 README.md 文档
- 记录正确的启动方式nohup + disown
- 记录端口规范
### v1.0.0
- 项目服务管理面板
- 状态检测、启动/停止控制
- 日志查看