my_cluster/AGENTS.md

语言约定

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

项目总览

家庭/小型基础设施的 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 等）。执行前必须先说明影响并等待确认。