部署与运维

首次部署的步骤见快速开始。这里说明 Docker 部署长期运行时需要知道的事：怎么访问、怎么升级、怎么备份、出了问题怎么看。

运行方式

compose.yaml 启动两个容器，共用同一个数据卷 /app/data：

服务	进程	作用
`worker`	`python -m reelay.main`	监听 Telegram、执行识别 / 转存 / 整理、控制 Bot、发送通知
`web`	`python -m reelay.web`	管理台与 API、Agent 用的 `/mcp`；只读写任务状态，不执行转存

数据库、配置、密钥、Telegram 会话、115 凭证与日志全部在数据卷里。镜像以 UID 10001 运行，全新的命名卷会沿用镜像里的属主，不用手动授权；想把数据放在宿主机目录里，见用宿主机目录存放数据。同一个数据库只能有一个 worker（启动时用文件锁保证），也不要把数据卷放在网络文件系统上：SQLite 的 WAL 与文件锁在 NFS / SMB 上不可靠。

镜像发布在 ghcr.io/derrors/reelay，支持 linux/amd64 与 linux/arm64，标签有版本号（如 1.0.0）、次版本号（如 1.0）和 latest（最新正式版）。

用宿主机目录存放数据

NAS 上常把数据放在宿主机目录里（如 compose 文件旁的 ./data），方便直接备份和查看。有两种做法：

以宿主机用户运行（推荐）：文件归你自己的用户，宿主机上可以直接读写。worker 与 web 两个服务都要加上 user、HOME 与挂载：

yaml

services:
  worker:
    user: "1000:1000"      # 你的 UID:GID，用 id 命令查看
    environment:
      HOME: /app/data      # 必须，见下
    volumes:
      - ./data:/app/data
  web:
    user: "1000:1000"
    environment:
      HOME: /app/data      # 加在 web 原有的 environment 里
    volumes:
      - ./data:/app/data

HOME 必须设：镜像里没有这个用户的家目录，115 客户端启动时要在家目录下建缓存；不设时它无法加载，转存与整理都不可用。指到数据目录，缓存也随数据一起保存。
先用这个用户建好目录（mkdir data），否则 Docker 会以 root 身份创建，容器写不进去。
外部插件直接放进 data/plugins/，不用再单独挂载 deploy/plugins。

沿用镜像的 UID 10001：只把挂载改为 ./data:/app/data，并先执行 sudo chown -R 10001:10001 data。之后在宿主机上要用 root 才能读这些文件。

访问与安全

Compose 默认只把管理台开放在宿主机的 127.0.0.1:28080。要从局域网或公网访问，把 compose.yaml 里 web 的端口改为 "28080:28080"，或者经反向代理访问（建议配 HTTPS），然后 docker compose up -d web。

第一次打开管理台时先设置登录密码（至少 8 个字符），设好后直接进入控制台。NAS 上通常没有浏览器，所以局域网里的设备也能做这一步，但只在请求来自局域网或本机、地址栏是 IP 或 localhost 时可用：公网来的请求不行；用域名打开也不行，这样借 DNS 重绑定伪装成本机的网页抢不到首次设置。经反向代理用域名访问的，先用 IP 地址打开一次设好密码。设好密码之前，除首次设置外的接口只接受本机地址。

设置密码后，只有登录、退出、登录状态、首次设置和健康检查（/api/health，只回答服务是否在线）可以匿名访问；其余 /api/* 接口，包括实时推送和接口文档（/api/docs、/api/openapi.json），都要求登录。登录会话有效期 7 天，Web 重启不影响；修改密码后其他会话全部失效。写操作只接受管理台自己页面发出的请求，同一台机器上其他端口或其他网站的页面发起的写请求一律拒绝。

登录失败按客户端 IP 计数：同一 IP 5 分钟内连续 5 次密码错误会被暂时拒绝。经反向代理访问时，Reelay 看到的都是代理的地址，要在 .env 里用 REELAY_FORWARDED_ALLOW_IPS 写上代理的地址（Docker 网络里一般是网关，如 172.18.0.1），按代理转发的真实客户端地址计数；否则所有人共用一个计数，别人输错几次你也会被暂时挡在外面。

Agent 经 /mcp 接入时用的是独立的 MCP 访问令牌，与登录密码无关，见 Agent 接入。

版本、升级与回滚

升级到 .env 里 REELAY_VERSION 指定的版本（不写时为 latest）：

bash

docker compose pull
docker compose up -d

升级前先看 GitHub Release 或 CHANGELOG。数据库结构会随版本升级，结构升级后旧版本程序会拒绝打开它，所以：

升级前先备份数据卷；
要回滚时，把 REELAY_VERSION 改回原来的版本，并连同数据卷一起恢复到升级前的备份。

从源码构建

需要改代码，或网络拉不到 GHCR 时，在仓库目录用 compose.build.yaml 覆盖镜像、在本机构建：

bash

docker compose -f compose.yaml -f compose.build.yaml build \
  --build-arg NPM_REGISTRY=https://registry.npmmirror.com/ \
  --build-arg PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple   # 国内网络可加这两个镜像源
docker compose -f compose.yaml -f compose.build.yaml up -d

之后的 run、restart、logs 等命令也要带上这两个 -f，否则 Compose 会改用发布的镜像。

备份与迁移

所有状态都在数据卷 reelay-data 里。备份前先停止两个服务，保证数据库与会话一致：

bash

docker compose stop
docker run --rm -v reelay_reelay-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/reelay-data-$(date +%Y%m%d).tgz -C /data .
docker compose start

数据卷的实际名称是「项目目录名_reelay-data」，可以用 docker volume ls 确认。用宿主机目录存放数据时，停止服务后直接打包这个目录即可。迁移到新机器时，在新机器上恢复同一个数据卷再启动即可；不要用 docker compose down -v，它会删除数据卷。

外部扩展

把扩展（插件目录，或单个 *.py 文件）放进 compose.yaml 同目录的 deploy/plugins/，它以只读方式挂载到 /app/data/plugins，docker compose restart 后生效，不用重建镜像。扩展以 Reelay 进程的权限运行，只放你信任的代码；导入失败不影响内置能力，错误显示在管理台「插件」页。写法见插件开发。

健康检查与故障恢复

两个容器都带健康检查：

worker：要求主进程心跳和 Telegram 连接在 30 秒内有效。还没配置或登录 Telegram 时主进程照常运行（识别、转存、控制 Bot 都可用），只是显示为 unhealthy，登录后自动恢复；
web：只检查 API 自身，不代表主进程在线或 115 凭证可用。

管理台总览的「运行状态」显示主进程心跳、正在使用的配置版本、各项连接状态，以及通知队列的积压与失败；页面底部显示当前版本号，报告问题时请一并附上。以下故障会通过控制 Bot 告警一次，恢复后再通知（告警经持久化队列投递，重启不丢；Telegram 断开期间发不出的告警，恢复后补发并注明发生时间）：

故障	Reelay 的处理
115 登录失效	暂停转存与整理（识别照常），任务原地等待、不消耗重试次数；在管理台重新扫码后 30 秒内自动继续
115 风控（访问上限、操作频繁）	所有 115 请求暂停 `p115.risk_cooldown_sec`（默认 1 小时），转存与整理暂停，任务到点自动继续、不算失败；冷却期间重启主进程也会接着冷却
Telegram 断开，或还没配置、登录，超过 `telegram.alert_after_sec`（默认 120 秒）	告警，恢复后的通知写明断开了多久。断开后（连接被重置、没有回应）主进程自己重新连接，连不上时每 30 秒再试，不用重启；没配置或没登录时每 30 秒重新检查，补上后自动接上。监听启动或重新连上时，按每个来源已收到的最大消息 ID 补拉停机或断开期间的消息（默认每个来源最多 200 条、7 天内）
转存后 115 迟迟没有落地	任务转「待人工」，后台自动只读复查（5 分钟起，间隔加倍，24 小时内），通过后照常整理。复查期间不打扰；连续 3 次核验结果都没有变化（如一个文件都没到）时提前提醒，大约在转存后半小时，后台仍继续复查；24 小时仍未通过、之前又没提醒过的，这时通知
配置文件写错	继续使用上一个有效版本，总览与设置页显示出错的文件和原因；修正文件之前管理台不能保存

设置何时生效：多数设置保存后约 1 秒生效；控制 Bot、并发数与日志级别在主进程启动时读取，Telegram 账号在监听连上时读取，改了之后执行 docker compose restart worker。

停止与重启：停止时会等待进行中的请求结束，Compose 留出 120 秒。被强制终止也没关系，下次启动从已保存的检查点继续；转存结果不明的任务只核验，不会重发。

常用命令

bash

docker compose ps                          # 状态与健康检查
docker compose logs --tail=100 worker web  # 最近日志（也可以在管理台侧栏「工具 → 运行日志」查看）
docker compose restart worker              # 改了需要重启的设置后
docker compose run --rm --no-deps -it worker python -m reelay.login   # 重新登录 Telegram
docker compose down                        # 停止并删除容器，数据卷保留

部署与运维 ​

运行方式 ​

用宿主机目录存放数据 ​

访问与安全 ​

版本、升级与回滚 ​

从源码构建 ​

备份与迁移 ​

外部扩展 ​

健康检查与故障恢复 ​

常用命令 ​

部署与运维

运行方式

用宿主机目录存放数据

访问与安全

版本、升级与回滚

从源码构建

备份与迁移

外部扩展

健康检查与故障恢复

常用命令