# Spark 运维

以本 Git 仓库的 main 作为当前配置来源，不混用历史实验目录里的 Compose。

## 目录约定

- 项目根目录：Git 管理的 Compose、Dockerfile、脚本、文档。
- `.env`：本机缓存路径、已有 API key 文件路径、代理；权限 0600，不提交 Git。
- `runtime-cache/`：原有编译缓存，保留挂载路径；不提交 Git。
- `archive/<时间>/legacy/`：整理前的部署脚本、Compose 和日志，只用于追溯。
- `archive/<时间>/experiments/`：历史实验及原始 Nsight trace；目录 0700。
- `archive/<时间>/tmp/`：本任务遗留的临时打包和检查文件。
- `.local-state/`：本机迁移、健康检查、资源与部署提交记录；目录 0700。
- 模型权重和 API key 继续使用原外部路径，不复制进仓库。

归档不是现用配置。旧 Compose 的相对路径依赖原目录，不能直接从 archive 启动。
原始 trace 可能含进程参数，不对外分享、不提交 Git。

## 更新与验证

```bash
git status --short
git pull --ff-only origin main
# 不随意拉取新的 nightly。更新镜像须先核实固定版本并构建。
./scripts/start.sh
./scripts/wait.sh
./scripts/test.sh
./scripts/test-prefix.sh
```

若 Spark 没有 Gitea 凭据，可由已登录的工作站传输 `git bundle`，在 Spark fetch 本地 bundle 后 fast-forward main。
不要把工作站 token 写进 Spark 的 Git remote；remote 始终使用不含凭据的仓库 URL。
启动和重载约需 10–13 分钟，会中断当前请求。

## 回退

`./scripts/start.sh no-prefix`：保留 128K + MTP，关闭前缀缓存。
`./scripts/start.sh baseline`：32K、无 MTP 的较保守配置。
回退后同样执行 wait 和 smoke 检查。实验图配置位于 experiments/graph，当前也限制为 128K。
不要把历史 262K 配置当成稳定回退。

日常看 `/proc/meminfo` 的 MemAvailable 和 `/proc/vmstat` 的 oom_kill 增量，不能只看容器 healthy。
测试时监控脚本的停止阈值只提供尽力保护。业务输出预算必须包含思考 tokens。