# AstrBot 部署与运维参考

> 更新于 2026-10-07。本文是已完成部署后整理的参考资料，记录已经实施并核对的状态；[AstrBot 扩展部署计划](../../plan/AstrBot部署方案.md) 是后续扩展规划，其中 NapCat、企业微信、公网反向代理等示例不代表已经部署。

## 1. 当前部署状态

| 项目 | 当前值 |
| --- | --- |
| Linux 设备 | `zrh-dracarys`，Tailscale IP `100.99.232.7` |
| Windows SSH 别名 | `zrh-server`（本机 `~/.ssh/config`） |
| 部署目录 | `/opt/astrbot` |
| Compose 文件 | `/opt/astrbot/docker-compose.yml` |
| 持久化数据 | `/opt/astrbot/data`，映射到容器 `/AstrBot/data` |
| 容器名 | `astrbot` |
| 镜像 | `m.daocloud.io/docker.io/soulter/astrbot:latest` |
| WebUI | 宿主机 `127.0.0.1:6185` → 容器 `6185`；仅本机监听 |
| 其他端口 | 容器 `6199` 仅 `expose`，未映射到宿主机 |
| 自动启动 | Docker、Tailscale 服务已设置开机启动；AstrBot 使用 `restart: unless-stopped` |

2026-10-07 核对结果：容器处于 `running`，无重启记录；`/opt/astrbot/data` 约 **119 MB**。一次即时采样显示容器约占 **1.16 GiB 内存**、CPU 约 **0.46%**，资源占用会随插件、会话和知识库变化。服务器当前的 Compose 只包含 AstrBot，一个单独的 NapCat 容器尚未部署。

> `latest` 镜像会随升级改变版本。查看 WebUI 左上角或容器启动日志，以确认当前实际版本；不要把这份记录中的资源采样当成固定配额。

## 2. 已完成的工作

1. 通过 Tailscale 和 SSH 连通 Linux；在 `/opt/astrbot` 部署 Docker Compose 版 AstrBot，数据持久化到 `data/`。
2. 管理面板通过 SSH 本地转发在 Windows 的 `http://127.0.0.1:6185` 使用；面板没有开放公网端口。
3. 已在 WebUI 中使用 DeepSeek 相关配置、人格设定、管理员和分段回复等功能，并安装/使用「表情包小偷」等插件。模型密钥、管理员密码和插件的具体运行参数均以 WebUI 当前设置为准，不写进本文。
4. 为「大肥鱼」表情包整理了 249 张图片，并在 Windows 下载目录生成 5 个分卷 ZIP。是否已经全部导入插件，应在「表情包小偷 → 表情包库」核对；准备好资源包不等于导入完成。
5. 排查过一次资源包上传报错：完整仓库 ZIP 约 290 MB，超过 AstrBot 的 128 MB 单次上传限制，服务端日志为 `413 Request Entity Too Large`。五个分卷均低于该限制。

未作为当前状态确认的项目：NapCat/企业微信接入、Tailscale Serve、公网域名或反向代理、知识库文档导入。相关内容见原部署方案，实施前须按现有配置重新核对。

## 3. 启动 AstrBot

### 服务器开机后

Docker、Tailscale 已设为开机启动，AstrBot 容器采用 `unless-stopped`，正常重启 Linux 后应自动恢复。先在 Windows PowerShell 检查：

```powershell
ssh zrh-server "docker ps --filter name=astrbot --format '{{.Names}} {{.Status}} {{.Ports}}'"
```

看到 `astrbot Up ...` 即为容器已启动。若没有运行，手动启动：

```powershell
ssh zrh-server
cd /opt/astrbot
docker compose up -d
docker compose ps
```

`docker compose up -d` 会按当前 Compose 文件创建或启动服务；现有数据位于 `/opt/astrbot/data`。不要为了日常启动而删除 `data/`、执行 `docker compose down -v`，也不需要重新安装插件。

### 在 Windows 打开管理面板

另开一个 PowerShell 窗口，建立 SSH 转发并保持窗口运行：

```powershell
ssh -N -L 6185:127.0.0.1:6185 zrh-server
```

浏览器打开 <http://127.0.0.1:6185>。关闭该 PowerShell 窗口只会断开管理面板的本地转发，**不会停止 Linux 上的 AstrBot**。如果本机 `6185` 已被占用，可改为 `ssh -N -L 6186:127.0.0.1:6185 zrh-server`，然后打开 <http://127.0.0.1:6186>。

当前地址中的 `127.0.0.1` 指使用浏览器的那台设备。手机无法直接使用 Windows 的 `127.0.0.1:6185`；若以后需要手机远程管理，可另行配置仅 Tailnet 内访问的 Tailscale Serve，不要直接把管理端口暴露到公网。

## 4. 常用运维命令

以下命令在 SSH 登录 Linux 后运行：

```bash
cd /opt/astrbot
docker compose ps                 # 查看状态
docker compose up -d              # 启动/恢复
docker compose restart astrbot    # 重启 AstrBot
docker logs --tail 100 astrbot    # 最近 100 行日志
docker logs -f astrbot            # 持续查看日志，Ctrl+C 退出查看
docker stats --no-stream astrbot  # 即时资源占用
du -sh /opt/astrbot/data          # 数据目录大小
```

只有确实需要停止服务时才运行 `docker compose stop astrbot`；之后用 `docker compose up -d` 恢复。`restart: unless-stopped` 不会自动恢复被手动停止的容器，直到再次启动它。

升级前先备份 `/opt/astrbot/data`，再执行 `docker compose pull` 和 `docker compose up -d`。`/opt/astrbot/backups` 当前为空目录，不能视为已有可恢复备份。升级和备份应另定维护时间，避免打断正在使用的机器人。

## 5. 故障速查

| 现象 | 首先检查 |
| --- | --- |
| Windows 打不开 `127.0.0.1:6185` | SSH 转发窗口是否还在；`docker compose ps` 是否显示 `astrbot` 运行；本机 `6185` 是否被占用。 |
| SSH 连不上 | Windows 与 Linux 的 Tailscale 是否在线；尝试 `tailscale ping 100.99.232.7`。 |
| WebUI 能打开但机器人不回复 | WebUI 的机器人/模型提供商状态，以及 `docker logs --tail 100 astrbot`。 |
| 上传表情包显示 Internal server error | 先检查文件大小；单文件超过 128 MB 会报 `413`。使用下载目录中的分卷包。 |
| 大量插件或知识库导入后变慢 | 用 `docker stats --no-stream astrbot` 看内存/CPU，并检查 `/opt/astrbot/data` 与磁盘空间。 |

Windows 上准备的分卷目录：`C:\Users\21031\Downloads\大肥鱼表情包-分卷导入-20261001`。这是本机文件，不在 Linux 的 `/opt/astrbot` 下；如需重装本机，应另行保留这些 ZIP。