# Linux 设备接入说明

> 适用对象：需要从 Windows、macOS、Linux 或移动设备访问家中 Linux 主机的使用者。本文围绕 Linux 主机说明接入边界；客户端专属操作记录不作为通用配置模板。

## 1. 接入目标

所有远程访问以 Linux 主机 `zrh-dracarys` 为目标：

| 项目 | 当前信息 |
| --- | --- |
| 主机名 | `zrh-dracarys` |
| 系统 | Ubuntu 24.04.5 + XFCE |
| Tailscale IP | `100.99.232.7` |
| 日常 SSH 用户 | `zrh` |
| SSH 端口 | `22` |
| 常驻业务 | Docker Compose / AstrBot；详情见 [设备概览](../../设备概览.md) |

标准访问路径为：

```text
客户端设备 → Tailscale tailnet → zrh@100.99.232.7:22 → sudo -i（按需）
```

不要将 SSH、AstrBot WebUI、NapCat 或未来的 code-server 管理端口直接映射到公网。外部文件共享只允许使用有独立鉴权和失效机制的专门方案。

## 2. 接入前检查

新客户端必须满足以下条件：

1. 已安装 Tailscale，并登录到与 Linux 相同的 Tailnet。
2. 已获设备审批，并满足 Tailnet ACL / policy。
3. 拥有该设备专属的 SSH 密钥对；不得复制其他设备的私钥。
4. 能访问 Linux 的 Tailscale IP，再排查 SSH，不要倒序处理。

客户端先执行：

```text
tailscale status
tailscale ping 100.99.232.7
```

Linux 上可由已有管理员会话确认：

```bash
sudo systemctl is-active ssh
sudo ss -lntp | grep ':22'
```

## 3. 连接层：先判断 Tailscale 路径

`tailscale status` 会显示到 Linux 的实际路径：

| 输出特征 | 含义 | 处理 |
| --- | --- | --- |
| `direct <公网IP>:<UDP端口>` | UDP 直连，性能最佳 | 正常使用 |
| `peer-relay ...` | 经 Tailnet 内的 Peer Relay 转发 | 可用；检查中继健康度 |
| `relay "tok"` 或其他 region | 回退到官方 DERP | 可用但延迟可能显著升高；按网络故障处置排查 |

截至 2026-10-08，`2024-bg-217` 到 Linux 曾稳定回退至 `relay "tok"`，并出现 `direct connection not established`。此前 11ms 的直连是历史观测值，不应作为持续可用的保证。完整的恢复顺序、Linux 端口映射和中继部署位置见 [Linux 设备稳定连接计划](../../plan/03-Linux设备稳定连接.md)。

## 4. SSH：默认使用普通账户

日常操作使用：

```bash
ssh zrh@100.99.232.7
sudo -i
```

推荐在客户端 SSH 配置中使用一个明确别名，例如：

```sshconfig
Host zrh-server
    HostName 100.99.232.7
    User zrh
    Port 22
    IdentityFile ~/.ssh/<该设备自己的私钥>
    IdentitiesOnly yes
    ServerAliveInterval 30
    ServerAliveCountMax 3
```

随后使用：

```text
ssh zrh-server
```

Linux 账号密码、root 密码、Tailscale 登录密钥和任何私钥都不应写入文档、聊天记录或脚本。

## 5. 新客户端的密钥接入规范

1. 在客户端生成独立 ED25519 密钥；私钥保留在该客户端。
2. 只将 `.pub` 公钥和 SHA-256 指纹交给现有 Linux 管理员。
3. 将公钥写入 `/home/zrh/.ssh/authorized_keys`，并按需使用 `from="<客户端 Tailscale IP>"` 限制来源。
4. 用显式密钥完成首次连接后，再写入客户端 SSH 别名。
5. 撤销设备时，仅删除该设备对应的公钥行；不要删除其他设备的授权。

通用 root SSH 仅用于救援或无人值守运维，不能替代日常 `zrh + sudo` 管理。若确有需要，使用 [SSH 密钥与 Root 维护规范](SSH密钥与Root维护规范.md) 的最小权限流程。

## 6. 已登记客户端

| 客户端 | 系统 | 用途 | 参考记录 |
| --- | --- | --- | --- |
| `2024-bg-217` | Windows，用户 `huawei` | 主操作终端、SSH / Remote-SSH / 网络验证 | [实际接入记录](../设备接入记录/2024-bg-217接入Linux记录.md) |
| `dracarys` | Windows | 辅助客户端；基础信息待补全 | [设备概览](../../设备概览.md) |

新增设备后，除完成 SSH 连接外，还必须更新设备概览中的角色、系统、Tailscale IP 与用途。

## 7. Linux 上服务的访问边界

| 服务 | 推荐访问方式 | 不应采用的方式 |
| --- | --- | --- |
| SSH | Tailscale + 独立 SSH 密钥 | 密码认证、共享私钥、公共端口映射 |
| AstrBot WebUI | SSH 本地转发到 `127.0.0.1:6185` | 直接公网暴露 6185 |
| code-server（若部署） | Tailnet 内 `100.99.232.7:8444` + 独立密码 | 绑定 `0.0.0.0` 或关闭认证 |
| 文件共享（若部署） | 专用 Funnel + Nginx + 鉴权 + 到期关闭 | 将 `/home`、`/etc`、`/root` 或管理接口公开 |

## 8. 故障速查

| 现象 | 先检查 | 下一步 |
| --- | --- | --- |
| `tailscale ping` 失败 | 设备登录、在线状态、ACL | 先修 Tailscale，再看 SSH |
| ping 经 DERP 且卡顿 | `tailscale netcheck`、代理是否开启 TUN | 查看 [远程接入计划](../../plan/02-Linux设备远程接入.md) 与稳定连接计划 |
| SSH 超时 | `Test-NetConnection 100.99.232.7 -Port 22` | 确认 Linux ssh 服务与 Tailnet 路径 |
| `Permission denied (publickey)` | 用户名、私钥路径、对应公钥、`from=` 限制 | 用 `IdentitiesOnly=yes` 显式指定私钥 |
| AstrBot 面板打不开 | SSH 本地转发窗口、容器状态 | 查看 [AstrBot 部署与运维参考](../服务运维/AstrBot部署与运维.md) |

## 9. 维护要求

当新增客户端、改变 SSH 授权、调整端口映射、修改 Tailnet policy 或改变 Linux 服务访问方式时：

1. 更新 [设备概览](../../设备概览.md)。
2. 若属于未完成工作，更新 [计划总表](../../plan/README.md)。
3. 若已经实施，更新对应 `deploy/` 或 `network/` 记录。
4. 不记录秘密，只记录可复现的命令、状态、验证结果与回滚方式。