# 家庭 Linux 服务与组网文档

本文档库记录三台设备的现状、Linux 服务部署、网络接入与后续计划。状态性文档只描述已经实施和核验的内容；未落地的设计统一放在 [`plan/`](plan/README.md)。

## 先看这里

- [设备概览](设备概览.md)：三台设备的角色、当前网络信息与 Linux 主机已部署服务。
- [Linux 设备接入说明](reference/远程接入/Linux设备接入说明.md)：以 Linux 主机为中心的统一接入入口、SSH 边界与故障速查。
- [部署计划总表](plan/README.md)：全部待办、优先级、状态定义和更新记录。
- [AstrBot 部署与运维参考](reference/服务运维/AstrBot部署与运维.md)：当前已完成业务服务的启动、日志、备份与故障处理。
- [Linux 设备稳定连接计划](plan/03-Linux设备稳定连接.md)：当前 Tailscale 回退 DERP 的原因、验证证据与恢复顺序。

## 文档结构

```text
docs/
├── 设备概览.md                 # 三台设备与 Linux 服务清单
├── plan/                       # 未实施或待决策的部署计划
├── reference/                  # 已完成内容沉淀的接入、服务运维规范
└── server/                     # Linux 宿主硬件和服务器化基线
```

## 阅读路径

### 管理 Linux 服务

1. 查看 [设备概览](设备概览.md)，确认服务是否已部署及其边界。
2. 对 AstrBot 使用 [部署与运维参考](reference/服务运维/AstrBot部署与运维.md)。
3. 涉及网络延迟、DERP 或直连问题时，使用 [Linux 设备稳定连接计划](plan/03-Linux设备稳定连接.md)。

### 新增或撤销客户端设备

1. 阅读 [Linux 设备接入说明](reference/远程接入/Linux设备接入说明.md)。
2. 阅读 [Linux 设备远程接入计划](plan/02-Linux设备远程接入.md)，确认路径健康度。
3. 依照 [SSH 密钥与 Root 维护规范](reference/远程接入/SSH密钥与Root维护规范.md) 创建独立密钥和最小权限授权。
4. 在 [设备概览](设备概览.md) 和 [计划总表](plan/README.md) 更新设备/任务状态。

### 规划新服务

1. 先在 [计划总表](plan/README.md) 建立或更新条目。
2. 仅在明确目标、权限、端口边界、回滚方式与验收条件后开始实施。
3. 完成后将最终事实写入 `deploy/` 或相关主题文档，并把计划标为“已完成”。

## 当前重点

- Windows `2024-bg-217` 到 Linux `zrh-dracarys` 当前经 `relay "tok"` 通信，直连不稳定；优先处理 UDP 直连，再考虑 Peer Relay 或自建 DERP。
- AstrBot 已运行，但数据备份与升级演练尚未形成可验证的流程。
- code-server、Funnel 文件共享、AstrBot 的 QQ/企业微信接入均仍是计划，不能视为已部署。

## 安全约定

- 私钥不得复制、提交或写入文档；每台设备独立一对 SSH 密钥。
- 日常管理使用 `zrh` 后再 `sudo -i`；root SSH 仅用于明确的维护/救援情形。
- 管理界面默认只在 localhost、SSH 隧道或 Tailnet 内开放；公网暴露必须有单独的计划、鉴权和失效机制。
- 每次变更 Tailscale policy、路由器端口映射、容器版本、服务端口或持久化数据，都必须同步更新实施记录和计划表。