# 服务矩阵（Service Matrix）

本文档定义当前项目的服务分层、默认启动策略与脚本入口。

## 1. 服务分层

| 服务 | 角色 | 默认端口 | 是否默认启动 | 启动脚本 | 停止方式 |
|---|---|---:|---|---|---|
| backend | 核心搜索 API | 6002 | 是 | `scripts/start_backend.sh` | `scripts/service_ctl.sh stop backend` |
| indexer | 核心索引 API | 6004 | 是 | `scripts/start_indexer.sh` | `scripts/service_ctl.sh stop indexer` |
| frontend | 调试 UI | 6003 | 是 | `scripts/start_frontend.sh` | `scripts/service_ctl.sh stop frontend` |
| embedding | 向量服务（文本/图片） | 6005 | 否（按需） | `scripts/start_embedding_service.sh` | `scripts/service_ctl.sh stop embedding` |
| translator | 翻译服务（qwen/deepl） | 6006 | 否（按需） | `scripts/start_translator.sh` | `scripts/service_ctl.sh stop translator` |
| reranker | 重排服务（BGE） | 6007 | 否（按需） | `scripts/start_reranker.sh` | `scripts/service_ctl.sh stop reranker` |
| clip | CLIP 替代服务（legacy/可选） | 51000 | 否（按需） | `scripts/start_clip_service.sh` | `scripts/service_ctl.sh stop clip` |
| cnclip | CN-CLIP gRPC 服务（legacy/可选） | 51000 | 否（按需） | `scripts/start_cnclip_service.sh` | `scripts/service_ctl.sh stop cnclip` |

> 说明：`clip` 与 `cnclip` 都是 legacy 服务，脚本内部自带后台化与 PID 管理，`service_ctl.sh` 仅做编排与委托。

## 2. 统一控制入口

- 推荐统一入口：`scripts/service_ctl.sh`
- 支持命令：`start` / `stop` / `restart` / `status`

示例：

```bash
# 启动核心服务（backend/indexer/frontend）
./scripts/service_ctl.sh start

# 启动指定服务
./scripts/service_ctl.sh start backend indexer frontend translator reranker

# 查看所有服务状态
./scripts/service_ctl.sh status

# 停止全部已知服务
./scripts/service_ctl.sh stop
```

## 3. 默认与可选服务策略

- `./run.sh` 默认只启动核心服务：`backend/indexer/frontend`
- 如需启动可选能力，使用环境变量：

```bash
START_EMBEDDING=1 START_TRANSLATOR=1 START_RERANKER=1 ./run.sh
```

## 4. 兼容入口

以下脚本仍保留，用于兼容旧习惯，但内部已委托到统一控制脚本：

- `run.sh`
- `restart.sh`
- `scripts/start.sh`
- `scripts/stop.sh`