一键安装（含内置 PostgreSQL）
推荐推荐方式：脚本创建目录与 .env，数据库随容器启动，运维脚本同时生成。
curl -fsSL https://mediabot.top/deploy/install.sh | sudo bash -s -- --with-db安装完成后访问 http://<服务器IP>:9015/install，按向导填写数据库信息与管理员账号。
安装
部署在一台服务器上完成：执行脚本、启动容器，并在浏览器中填写数据库信息与管理员账号。 下文依次说明安装方式、部署结构、前置条件、安装后验证、首次配置顺序与日常运维，可直接跳转对应小节。
部署结构
全部服务运行在一个容器内，数据库可以内置，也可以沿用已有实例。
你的浏览器 仅访问 9015 端口
MediaBot 容器
网页界面 HTTP 接口 周期任务 安装向导
data/ 通过 bind 挂载持久化 数据库与外部服务 PostgreSQL / MySQL PT 站点 · 下载器 · 通知渠道
前置条件
以下任一项不满足都会导致安装中断，建议在安装前逐项确认。
| 项目 | 要求 |
|---|---|
| 操作系统 | Linux x86_64，能运行 Docker。Windows / macOS 建议在虚拟机或 NAS 的 Docker 中运行。 |
| 容器环境 | Docker Engine 与 Docker Compose v2（docker compose 形式）。 |
| 镜像 | registry.cn-guangzhou.aliyuncs.com/pt-tools/mediabot，公开拉取，无需登录。
|
| 数据库 | 使用 --with-db 会一并启动内置 PostgreSQL；也可以接入你已有的 PostgreSQL 或 MySQL。 |
| 端口 | 默认 9015，安装时可改。需要从你的浏览器访问。 |
| 数据目录 | ./data 通过 bind 挂载持久化，容器重建与升级都不会丢失。 |
| 出网 |
服务器需要能访问阿里云容器镜像服务（ACR）、https://mediabot.top，
以及你使用的 PT 站点和下载器。
|
| 资源 | 单容器 + 外部数据库。实际占用取决于订阅数量、并发任务与数据库规模，建议至少 2 核 / 2 GB 起步。 |
安装后验证
三项全部通过后再配置站点，否则后续故障难以区分是安装问题还是配置问题。
STEP 01 · 打开向导 访问 http://<服务器IP>:9015/install，填写数据库类型、地址、库名与账号密码。
STEP 02 · 等待容器重启
提交后容器在进程内完成建库迁移与管理员创建，随后主动退出；
restart: always 会将其重新启动，页面轮询后跳转至首页。
STEP 03 · 健康检查 确认服务处于就绪状态，再开始添加站点与订阅。
curl -fsS http://localhost:9015/health
返回非 2xx 或连接失败时，先看容器日志：docker compose logs -f app
首次配置顺序
按「站点 → 下载器 → 订阅」依次配置；顺序颠倒时，后一步缺少前置数据，问题难以定位。
STEP 01 · 站点 填写站点地址与登录凭据，同步成功后确认分享率、做种数与 H&R 已读取。
STEP 02 · 下载器 填写下载器地址与凭据并测试连接；同时确认默认下载目录，避免文件落在预期之外的位置。
STEP 03 · 订阅 先用一条订阅验证搜索与匹配结果，数量正常后再批量添加。
每一步的字段说明与验收标准见快速上手；安装期故障见下方故障排查。
日常运维：升级、回滚、备份
安装脚本会在安装目录（默认 /opt/mediabot）生成四个运维脚本：
升级负责完整流程、回滚只切换镜像、备份与恢复处理数据。
动作 命令 说明 升级 ./upgrade.sh备份 → 拉镜像 → 迁移 → 启动 → 健康检查，失败自动回滚镜像。 回滚 ./rollback.sh只回退镜像版本，不撤销数据库迁移。 备份 ./backup.sh立即备份到 ./data/backups。 恢复 ./backup.sh restore <文件>恢复前会先停服，请确认当前没有正在执行的任务。
未使用安装脚本、仅维护 docker-compose.yml 的部署，也可通过
docker compose run --rm app backup 等子命令完成相同操作。
完整的升级步骤、确认清单与回滚说明见升级与回滚。
安装阶段故障排查
安装期常见故障如下；使用期问题见常见问题。
脚本执行完成，但页面无法访问
先确认容器状态：docker compose ps；再检查是否在反复重启：docker compose logs -f app。
容器正常时，常见原因是端口：本机防火墙是否放行、9015 是否被其他程序占用、
公网 IP 对应的安全组是否开放。
向导提交后页面长时间无响应
此为预期行为：容器在内部完成建表与管理员创建后主动退出，由 restart: always 重新启动，
这段时间内的请求会失败。等待十余秒后刷新即可。超过一分钟仍无法访问时，在日志中查找迁移失败的错误。
提示无法连接数据库
按以下顺序排查：数据库地址是否写成 localhost（在容器内指向容器自身，应填写宿主 IP 或服务名）、
数据库是否对容器网段放行、账号是否缺少建库建表权限、连接串中的库名与端口是否正确。
使用 --with-db 安装时，先确认内置数据库容器已启动。
容器报权限错误，无法写入 data 目录
容器内以 uid 1000 运行，bind 挂载会覆盖容器内的目录所有者。
在宿主机执行 chown -R 1000:1000 /opt/mediabot/data 通常可解决；
SELinux 或 AppArmor 拦截时，还需额外放行该目录。
升级后 /health/ready 持续返回 503
将 .env 中的 APP_VERSION 改回升级前的版本，再执行 docker compose up -d。
注意迁移不会自动撤销：若新版本修改过表结构，需使用升级前的备份恢复。