服务矩阵（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

示例：

# 启动核心服务（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
• 如需启动可选能力，使用环境变量：

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

4. 兼容入口

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

• run.sh
• restart.sh
• scripts/start.sh
• scripts/stop.sh