# 语言约定

本项目首要语言为**中文**。所有思考过程、回复、代码注释及文档均使用中文。

# 项目总览

家庭/小型基础设施的 Ansible 管理仓库。没有 role/playbook 目录结构，inventory 的 `.ini` 文件和 playbook 的 `.yml` 文件都平铺在**仓库根目录**（不存在 `inventory/` 目录）。

## Inventory 分组

| 文件 | 组名 | 主机 | 登录用户 |
|------|------|------|----------|
| `pve.ini` | `proxmox` | pvehome, pvetower | root |
| `debian_servers.ini` | `cloud_servers` | hkyc1, baota-home, 1panel-home, baota-tower, 1panel-tower | root |
| `fnos.ini` | `fnos` | fn-home, fn-tower（飞牛 OS NAS） | carry |
| `openwrt.ini` | `openwrt` | openwrt-home, openwrt-tower（路由器） | root |

- 主机名后缀 `-home` / `-tower` 表示两个物理站点。
- `ansible.cfg` **未配置默认 inventory**，因此每条命令都必须显式指定 `-i <file>.ini`，例如 `ansible proxmox -i pve.ini -m ping`。

## 认证约定

- inventory 里 **不写明文密码**，而是引用变量 `{{ ssh_password1|2|3 }}`，其真实值定义在 `group_vars/all/secret.yml`。
- 优先用 SSH key（`ansible_ssh_private_key_file=~/.ssh/id_ed25519`），密码作为回退。
- `ansible_become_pass` 在 `secret.yml` 中统一设为 `{{ ansible_ssh_pass }}`（sudo 密码 = SSH 密码），不在各组 `:vars` 里重复设置。
- ⚠️ `group_vars/all/secret.yml` 是**未加密的明文密码且已提交进 git**（`.gitignore` 未覆盖它）。绝不要在输出/日志中回显这些密码，也不要把新密钥硬编码到别处。

## Playbook

- `apt-upgrade.yml`：`hosts: all` + `become: yes`，执行 `apt full-upgrade`。⚠️ openwrt 用 opkg 而非 apt，对 `all` 跑此 playbook 会在 openwrt 上失败，需按组限定目标。
- `fix-auto-bind.yml`：仅 `hosts: fnos`，部署 bind-mount 的 systemd service/timer，将 NAS 外挂盘目录挂到 `/vol1/1000`。

## 注意事项

- 提权操作（apt、systemctl 等）必须加 `-b`（become/sudo），因 proxmox/cloud_servers/openwrt 虽为 root 免提权，但 fnos 用户 `carry` 需要 sudo。
- 飞牛 OS 用户无 `/home`，`ansible.cfg` 已配置 `remote_tmp = /tmp/.ansible-${USER}`。
- 优先用 ansible 命令操作远程主机（如 `ansible <group> -i <file>.ini -m shell -a '<cmd>' -b`），不要自己拼 ssh。
- 跑 ansible 时乐观地直接执行，不要预先检查 `.ini` 是否存在；出错再诊断。
- `CLAUDE.md` 是指向本文件的软链接，只需维护 `AGENTS.md`。
- **禁止在未经用户明确确认的情况下执行任何破坏性操作**（删除文件/目录、卸载软件包、`rm -rf` 等）。执行前必须先说明影响并等待确认。