diff --git a/docs/infra.md b/docs/infra.md
new file mode 100644
index 0000000..edc1ebd
--- /dev/null
+++ b/docs/infra.md
@@ -0,0 +1,94 @@
+# 基础设施 / 运行环境
+
+**不含任何凭据值**。Token、密码、cookie 只存 dev1 的 `~/.secrets/`。
+
+## 机器
+
+| 属性 | 值 |
+|---|---|
+| 名字 | **dev1** |
+| 供应商 / 可用区 | 腾讯云，广州 |
+| OS | Ubuntu 22.04 LTS (jammy) |
+| CPU / RAM | 4 核 / 3.3 GiB（+ 4 GiB swap） |
+| 磁盘 | 40 GB（`/dev/vda2`，ext4），部署后用 12 GB，可用约 27 GB |
+| 用户 | `ubuntu` |
+| apt 镜像 | `mirrors.tencentyun.com`（默认） |
+
+## SSH
+
+本地 `~/.ssh/config` 用 `Host dev1` 别名；密钥 `~/.ssh/GuangZhou.pem`（mode 600）。只允许 key 登录，密码登录关闭。
+
+## 仓库位置
+
+```
+~/repo/FacereDataset/
+```
+
+- clone 时用 `GIT_LFS_SKIP_SMUDGE=1` 省流（LFS 对象只在真正需要核对历史数据时 `git lfs pull <path>`，平时不拉）
+- `git lfs install --skip-smudge` 已配，后续 `git pull` 也不会自动拉 blob
+- origin remote 带 Gitea token（token 值见 `~/.claude/.../memory/reference_gitea.md`，服务器上直接存在 `.git/config` 里）
+
+## 已装工具
+
+| 工具 | 版本 | 装法 |
+|---|---|---|
+| git | 2.34.1 | apt（系统自带） |
+| git-lfs | 3.0.2 | `apt install git-lfs` |
+| jq | 1.6 | apt |
+| uv | 0.11.7 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` → `~/.local/bin/uv` |
+| python | 3.10.12 | apt（系统自带，`pyproject.toml` 要求 `>=3.10`） |
+
+`~/.local/bin` 已加入 `~/.bashrc` 的 `PATH`。
+
+## 凭据目录
+
+```
+~/.secrets/              mode 700
+├── oshwhub-cookies.txt  # Netscape 格式（Charles 从浏览器导出）
+└── ...
+```
+
+**规则（重申）**：
+- 不入 git、不入日志、不入 metadata.json、不打 echo
+- 换号 / 重登事件写到 `docs/secrets.md`（仅事件日期与事由，不含值）
+- 文件权限 600，目录 700
+
+## Python 依赖 / 网络
+
+- `uv sync` 用清华 pypi 镜像加速：`export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple`
+- 默认用系统 Python 3.10：`UV_PYTHON_PREFERENCE=only-system`
+- 这两个 env var 建议加到 `~/.bashrc` 或 profile
+
+```bash
+# 建议追加到 ~/.bashrc
+export PATH="$HOME/.local/bin:$PATH"
+export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
+export UV_PYTHON_PREFERENCE=only-system
+```
+
+## 长跑 / 调度
+
+- 当前：手动 `tmux new -s crawl` 里跑，断开不受影响
+- 后续：爬虫跑稳后套 `systemd timer`（每周增量），配置位置 `/etc/systemd/system/facere-crawl.{service,timer}`
+
+## 日志
+
+- 爬虫 stdout/stderr 落 `~/logs/<site>-<YYYYMMDD>.log`（`~/logs/` 目录首次运行前创建）
+- `~/logs/` 不纳入 git
+- 超过 30 天用 `logrotate`（待配）
+
+## 磁盘应急策略
+
+当前阈值（需配 cron 告警）：
+
+| 使用率 | 动作 |
+|---|---|
+| 70% | 邮件告警 |
+| 85% | 停新批次爬取；只做增量 |
+| 95% | 停一切爬取；人工介入 |
+
+## 变更历史
+
+| 日期 | 变更 |
+|---|---|
+| 2026-04-23 | dev1 首次部署：apt install git-lfs jq / 装 uv / clone 仓库（skip LFS smudge）/ 创建 `~/.secrets/` / `uv sync` 通过 |