# Telegram 销售归档与风控系统 1Panel 部署说明

本文档面向 1Panel 用户。1Panel 只负责网站域名、反向代理和 SSL；应用本身由 `/opt/tg-sales-archive/docker-compose.prod.yml` 运行。

## 1. 部署边界

- 1Panel：管理域名、SSL、反向代理。
- Docker Compose：运行 backend、backend-scheduler、MySQL、Redis、MinIO、Telegram worker。
- 反向代理目标固定为 `http://127.0.0.1:8080`。
- 项目不要放到 `public_html` 或任何网站公开目录。
- 推荐安装目录：`/opt/tg-sales-archive`。
- 不要执行 `docker compose down -v`，这个命令会删除数据 volume。

## 2. 服务器要求

- VPS、云服务器或独立服务器。
- 有 root SSH 权限。
- 已安装 Docker Engine 和 Docker Compose plugin。
- 建议 Ubuntu 22.04/24.04 或 Debian 12。
- 至少 2 核 CPU、4 GB 内存、40 GB 磁盘；附件多时建议 100 GB 以上。

MySQL、Redis 不要公网开放。MinIO 默认不要公网开放，生产 Compose 只监听本机 `127.0.0.1:9000/9001`。

## 3. 一键安装并自动绑定域名

推荐使用 `--auto-caddy`。安装脚本会把 `--domain` 写入生产服务器本地 `.env`：

```text
APP_URL=https://t.jvniu.com
```

同时，脚本会在生产服务器本地安装/配置 Caddy，写入 `/etc/caddy/Caddyfile` 的托管配置块：

```caddy
t.jvniu.com {
    reverse_proxy 127.0.0.1:8080
}
```

Caddy 会自动申请 HTTPS 证书。Docker 镜像仍然是通用镜像，不包含域名；以后换域名只需要修改 `.env` 的 `APP_URL` 和 Caddyfile，不需要重新 build 镜像。

```bash
mkdir -p /opt/tg-sales-archive-installer
cd /opt/tg-sales-archive-installer

curl -fsSL https://codex.jvniu.com/tg-sales/install.sh -o install.sh
curl -fsSL https://codex.jvniu.com/tg-sales/checksums.txt -o checksums.txt

sha256sum -c checksums.txt --ignore-missing
less install.sh

bash install.sh \
  --domain https://t.jvniu.com \
  --admin-email tony@jvniu.com \
  --install-dir /opt/tg-sales-archive \
  --auto-caddy
```

安装脚本会在生产服务器本地生成 `.env`、`APP_KEY`、数据库密码、MinIO 密钥、内部 API token 和初始管理员密码。密码不会从 Codex 下载服务器获取，也不会上传回 Codex。

安装完成后，脚本会显示一次初始管理员密码。请立即登录后台修改密码。

## 4. 1Panel 创建网站

如果你已经使用 `--auto-caddy`，通常不需要再让 1Panel 接管同一个域名的 80/443 端口，避免和 Caddy 冲突。

如果你决定不用 Caddy，而是让 1Panel 负责反向代理，则安装时不要传 `--auto-caddy`，并在 1Panel 中创建“反向代理”网站。

- 域名示例：`t.jvniu.com`
- 代理地址：`http://127.0.0.1:8080`
- SSL：建议使用 Let's Encrypt。
- 不建议使用自签名证书。
- HSTS：证书没有正确配置前不要开启。

如果浏览器一直强制跳 HTTPS 或证书异常，可能是 HSTS 缓存。Chrome 可在下面页面清理：

```text
chrome://net-internals/#hsts
```

## 5. 生产环境配置

生产环境 `.env` 位于：

```text
/opt/tg-sales-archive/.env
```

要求：

- `.env` 权限必须是 `600`。
- `APP_ENV=production`
- `APP_DEBUG=false`
- `.env` 不要发给开发商。
- `.env` 不要上传到 Git。
- `.env` 不要放进网站公开目录。

正式多账号运营时，请登录后台进入“API 应用”，创建 Telegram API App，并把 TG 账号绑定到对应 API App。`.env` 中的 `TG_API_ID/TG_API_HASH` 只作为旧账号兼容回退。

## 6. Telegram Worker 首次登录

先在后台创建：

1. Telegram API 应用。
2. 销售人员。
3. TG 账号，例如 `sales01`。
4. 将 TG 账号绑定到 API 应用。

首次登录 `sales01`：

```bash
cd /opt/tg-sales-archive
docker compose -f docker-compose.prod.yml run --rm -it tg-worker-sales01
docker compose -f docker-compose.prod.yml up -d tg-worker-sales01
```

其他账号同理：

```bash
docker compose -f docker-compose.prod.yml run --rm -it tg-worker-sales02
docker compose -f docker-compose.prod.yml up -d tg-worker-sales02
```

说明：

- Telegram session 存在 Docker volume `tg_sales_tg_sessions` 中。
- 不要把 session 文件发给开发商。
- 不要把 session 打包进 release。
- `upgrade.sh` 会保留 session volume。

## 7. 历史消息回填

系统默认优先实时同步新消息。需要补历史消息时，请对单个账号手动执行一次回填，避免一次性扫太多会话。

示例：回填 `sales01` 最近 50 个会话、每个会话最近 200 条消息：

```bash
cd /opt/tg-sales-archive
docker compose -f docker-compose.prod.yml stop tg-worker-sales01
docker compose -f docker-compose.prod.yml run --rm -it \
  -e BACKFILL_ONLY=1 \
  -e BACKFILL_DIALOG_LIMIT=50 \
  -e BACKFILL_MESSAGES_PER_DIALOG=200 \
  tg-worker-sales01
docker compose -f docker-compose.prod.yml up -d tg-worker-sales01
```

说明：

- 回填会复用该账号已有 Telegram session。
- 回填不会物理删除已归档消息。
- 回填会下载历史消息中的附件到 MinIO。
- 如果历史消息已经被 Telegram 删除，Telethon 无法再取回原文或附件。
- 如果历史编辑已发生，回填只能拿到当前可见内容，不能还原编辑前历史。

## 8. 健康检查

```bash
cd /opt/tg-sales-archive
bash healthcheck.sh --install-dir /opt/tg-sales-archive
```

健康检查会检查：

- Docker 和 Docker Compose。
- MySQL healthy。
- Redis healthy。
- backend 和 backend-scheduler 是否运行。
- `/api/health`
- `/internal/health`
- `/login`
- backend 最近 100 行日志中是否有明显 ERROR。

## 9. 备份策略

建议每天备份一次，并将备份加密后同步到独立存储。

```bash
cd /opt/tg-sales-archive
bash backup.sh --install-dir /opt/tg-sales-archive
```

备份目录默认：

```text
/opt/tg-sales-archive-backups/YYYYMMDD_HHMMSS/
```

备份内容：

- `.env`
- MySQL SQL dump
- MySQL volume
- MinIO volume
- Telegram session volume
- backend storage volume
- Redis volume
- `docker-compose.prod.yml`
- 当前版本信息和校验文件

`.env` 包含生产密码、APP_KEY、数据库密码、MinIO 密码和内部 Token，请加密保存，不要发送给开发商，不要上传到 Git。

## 10. 升级策略

升级前脚本会自动备份，不会覆盖 `.env`，不会重置密码，不会删除 volume。

```bash
cd /opt/tg-sales-archive
bash upgrade.sh --install-dir /opt/tg-sales-archive
```

升级脚本会：

- 备份 `.env`、数据库和关键 volume。
- 下载新版 compose 和脚本。
- 加载新版离线镜像。
- 执行 `docker compose up -d`。
- 执行 `php artisan migrate --force`。
- 清理并重建 Laravel 生产缓存。
- 重启 backend 和 backend-scheduler。
- 执行健康检查。

## 11. 常用命令

查看容器：

```bash
cd /opt/tg-sales-archive
docker compose -f docker-compose.prod.yml ps
```

查看 backend 日志：

```bash
docker compose -f docker-compose.prod.yml logs --tail=100 backend
```

查看 worker 日志：

```bash
docker compose -f docker-compose.prod.yml logs --tail=100 tg-worker-sales01
```

重启 backend：

```bash
docker compose -f docker-compose.prod.yml restart backend backend-scheduler
```

启动所有预置 worker：

```bash
docker compose -f docker-compose.prod.yml up -d \
  tg-worker-sales01 tg-worker-sales02 tg-worker-sales03 tg-worker-sales04 tg-worker-sales05 \
  tg-worker-sales06 tg-worker-sales07 tg-worker-sales08 tg-worker-sales09 tg-worker-sales10
```

## 11. 严禁操作

不要执行：

```bash
docker compose down -v
```

不要把这些文件或数据发给开发商：

- `/opt/tg-sales-archive/.env`
- Telegram session volume
- 数据库备份
- MinIO 附件备份

不要公网开放：

- MySQL `3306`
- Redis `6379`
- MinIO `9000/9001`

1Panel 只代理 `http://127.0.0.1:8080`。