siemens_ragas/docs/superpowers/specs/2026-06-22-linux-deploy-design.md

Linux 一键部署脚本设计

日期: 2026-06-22
状态: 已批准，待实现
范围: 为 siemens_ragas 项目提供 Linux 环境的部署与运维脚本（无 Docker，无 systemd）。

---

1. 目标

提供四个 Bash 脚本，覆盖 Linux 服务器上的完整生命周期：

脚本	职责
deploy.sh	一键完成环境检查、依赖安装、配置初始化、启动服务
start.sh	仅启动 Web 服务（已部署后复用，不重装依赖）
stop.sh	停止后台 Web 服务
run_eval.sh	运行单次评估（对应 Windows 的 run_eval.ps1）

---

2. 约束与假设

• Linux 目标环境有 PyPI 网络访问（pip 可直接安装）
• 代码已通过 git clone 或文件拷贝到服务器
• 使用 pip + venv（不使用 uv）
• Web 服务监听 0.0.0.0:8800（内网可达）
• 后台运行使用 nohup，PID 写入 .server.pid，日志追加到 logs/server.log
• 所有脚本均放在仓库根目录，路径相对于 $SCRIPT_DIR

---

3. deploy.sh 详细设计

3.1 阶段 1：Python 版本检查

require Python >= 3.12

• python3 --version 解析 major.minor
• 不满足则打印错误并 exit 1
• 满足则打印 [OK] Python X.Y.Z

3.2 阶段 2：虚拟环境

• 目标路径：$SCRIPT_DIR/.venv
• 已存在则跳过创建（打印 [OK] .venv already exists）
• 不存在则 python3 -m venv .venv

3.3 阶段 3：依赖安装

.venv/bin/pip install --upgrade pip -q
.venv/bin/pip install -e . -q          # 安装 pyproject.toml 中的依赖
.venv/bin/pip install fastapi uvicorn httpx -q  # Web 服务额外依赖

• 失败则打印错误并 exit 1
• fastapi、uvicorn、httpx 在 pyproject.toml 中未列，需单独安装

3.4 阶段 4：配置文件

• 若 .env 不存在：cp .env.example .env，打印警告提示用户编辑后再启动
• 若 .env 已存在：跳过，打印 [OK] .env found

3.5 阶段 5：目录初始化

创建以下目录（mkdir -p，幂等）：

• configs/ — LLM Profile 持久化存储
• logs/ — 评估日志 + 服务器日志
• outputs/ — 评估运行产物
• datasets/ — 原始数据集

3.6 阶段 6：Demo 数据

• 检查 outputs/kba-knowledge-base-offline-baseline/ 是否存在
• 不存在则运行 .venv/bin/python scripts/seed_sample_run.py
• 失败时打印 [WARN]（非致命，报告页为空但服务可启动）

3.7 阶段 7：端口检测

• 默认端口 8800
• 用 ss -tlnp 或 netstat -tlnp 检查是否占用
• 占用则尝试 8801，仍占用则报错退出

3.8 阶段 8：启动服务

nohup .venv/bin/python webmain.py \
    --host 0.0.0.0 \
    --port $PORT \
    >> logs/server.log 2>&1 &
echo $! > .server.pid

• 等待 2 秒后用 kill -0 $PID 检测进程是否存活
• 存活则打印 URL 和 stop 方法
• 未存活则打印 [ERROR] Server failed to start. Check logs/server.log. 并 exit 1

---

4. start.sh 详细设计

单独负责启动，不做任何环境初始化。

#!/usr/bin/env bash
# 检查 .venv 存在
# 端口检测（同 deploy.sh 逻辑）
# 检查 .env 存在（不存在则 warn 但不阻止）
# nohup 启动 + PID 文件 + 存活验证
# 打印 URL

---

5. stop.sh 详细设计

#!/usr/bin/env bash
# 读取 .server.pid
# 若文件不存在：打印 "No server PID file found." 退出
# kill $PID
# 等待 2 秒，若进程仍存活用 kill -9
# 删除 .server.pid
# 打印 "Server stopped."

---

6. run_eval.sh 详细设计

对应 Windows 的 run_eval.ps1。

用法:
  ./run_eval.sh                          # online eval (默认)
  ./run_eval.sh offline                  # offline smoke
  ./run_eval.sh scenarios/xxx.yaml       # 自定义场景
  ./run_eval.sh online DEBUG             # 自定义日志级别

• 参数 1（Scenario）：online / offline / 文件路径，默认 online
• 参数 2（LogLevel）：DEBUG / INFO / WARNING / ERROR，默认 INFO
• 场景别名映射：
  • online → scenarios/online/siemens-pdf-question-bank-online.yaml
  • offline → scenarios/offline/siemens-pdf-offline-smoke.yaml
• 时间戳日志文件：logs/eval_$(date +%Y-%m-%d_%H%M%S).log
• 环境变量：PYTHONIOENCODING=utf-8 PYTHONPATH=.
• 调用：.venv/bin/python main.py --scenario $SCENARIO --log-file $LOG_FILE --log-level $LOG_LEVEL
• 非零退出码时打印错误并 exit 1

---

7. 通用约定

• 所有脚本首行：#!/usr/bin/env bash
• set -euo pipefail — 错误立即退出，未定义变量报错，管道错误传播
• SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" — 从任意目录执行均正确
• cd "$SCRIPT_DIR" — 切换到仓库根目录
• 颜色输出：绿色 [OK]、黄色 [WARN]、红色 [ERROR]（检测 tty，非交互式终端降级为无色）
• 执行权限：脚本自身需要 chmod +x（在 deploy.sh 内对其他脚本自动 chmod）

---

8. 不在范围内

• Docker / docker-compose 支持
• systemd service 配置
• Nginx 反向代理配置
• SSL/TLS 配置
• 离线/内网镜像源配置