sms_forwarder/docs/deployment.md

# SMS Forwarder 部署指南

本指南介绍如何使用 Docker 部署 SMS Forwarder 服务器。

## 推荐部署方式：Docker

Docker 部署具有以下优势：
- ✅ 环境一致性，无依赖问题
- ✅ 一键部署，简单快速
- ✅ 自动重启和健康检查
- ✅ 资源隔离和限制
- ✅ 易于备份和迁移

## 快速开始

### 1. 环境要求

- Docker 20.10+
- Docker Compose 2.0+
- 2GB+ 可用内存
- 开放端口 12152

### 2. 克隆项目

```bash
git clone https://gitea.nosuchip.de/zack/sms_forwarder.git
cd sms_forwarder
```

### 3. 配置服务

```bash
# 复制配置文件模板
cp config.example.yaml config.yaml

# 编辑配置文件
nano config.yaml
```

### 4. 一键部署

```bash
# 执行自动部署脚本
./scripts/deploy.sh
```

部署脚本会自动：
- 检查 Docker 环境
- 构建应用镜像
- 启动服务容器
- 运行健康检查
- 显示服务信息

## 手动部署步骤

如果你不想使用自动部署脚本，可以手动执行以下步骤：

### 1. 构建镜像

```bash
docker build -t sms-forwarder:latest .
```

### 2. 启动服务

#### 只启动 SMS Forwarder
```bash
docker-compose up -d
```

#### 同时启动 SMS Forwarder 和 Gotify
```bash
docker-compose --profile gotify up -d
```

### 3. 验证部署

```bash
# 检查容器状态
docker-compose ps

# 查看日志
docker-compose logs -f sms-forwarder

# 测试健康检查
curl http://localhost:12152/health
```

## 配置说明

### 核心配置项

编辑 `config.yaml` 文件，配置以下关键项：

```yaml
# 服务器配置
server:
  host: "0.0.0.0"
  port: 12152
  api_key: "your-secret-api-key"  # 必须修改

# 通知服务配置
notifications:
  services:
    # Gotify（推荐，低延迟）
    - name: "gotify"
      url: "gotifys://your-domain.com/YOUR_APP_TOKEN"
      enabled: true

    # ntfy（备用）
    - name: "ntfy"
      url: "ntfy://your-unique-topic/"
      enabled: true
```

### 推送服务选择

1. **自建 Gotify**（最推荐）
   - 延迟：1-3 秒
   - 完全自主控制
   - 启动方式：`docker-compose --profile gotify up -d`

2. **ntfy**（简单易用）
   - 延迟：5-15 秒
   - 无需自建服务器
   - 在 Android 上安装 ntfy 应用并订阅主题

## 服务管理

### 使用管理脚本

项目提供了便捷的管理脚本：

```bash
# 查看所有可用命令
./scripts/docker-manage.sh help

# 常用命令
./scripts/docker-manage.sh status    # 查看服务状态
./scripts/docker-manage.sh logs      # 查看实时日志
./scripts/docker-manage.sh test      # 发送测试通知
./scripts/docker-manage.sh restart   # 重启服务
./scripts/docker-manage.sh stop      # 停止服务
```

### 手动管理命令

```bash
# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f sms-forwarder

# 重启服务
docker-compose restart sms-forwarder

# 停止所有服务
docker-compose down

# 重新构建镜像
docker-compose build --no-cache
```

## 测试部署

### 自动测试

```bash
# 使用测试脚本
./scripts/test-docker.sh
```

### 手动测试

```bash
# 1. 健康检查
curl http://localhost:12152/health

# 2. 查看服务状态
curl http://localhost:12152/status

# 3. 发送测试通知
curl -X POST "http://localhost:12152/notify/simple" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-api-key",
    "content": "测试通知",
    "sender": "测试"
  }'
```

## 生产环境配置

### 1. 安全设置

```yaml
# config.yaml
security:
  # 限制访问 IP（可选）
  allowed_ips: ["192.168.1.100"]  # 你的 iPhone IP
  # 请求频率限制
  rate_limit: 60
```

### 2. 使用强 API 密钥

```bash
# 生成强密钥
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```

### 3. 反向代理（可选）

如果需要 HTTPS 或域名访问，可以使用 nginx：

```bash
# 启动带 nginx 的配置
docker-compose -f docker-compose.prod.yml --profile nginx up -d
```

## 监控和维护

### 1. 日志管理

```bash
# 查看实时日志
docker-compose logs -f sms-forwarder

# 查看最近 100 行日志
docker-compose logs --tail=100 sms-forwarder

# 查看错误日志
docker-compose logs sms-forwarder | grep ERROR
```

### 2. 资源监控

```bash
# 查看容器资源使用
docker stats sms-forwarder --no-stream

# 查看详细信息
./scripts/docker-manage.sh stats
```

### 3. 数据备份

```bash
# 备份配置和数据
tar -czf sms_forwarder_backup_$(date +%Y%m%d).tar.gz \
  config.yaml logs/ data/ gotify_data/

# 恢复备份
tar -xzf sms_forwarder_backup_20240117.tar.gz
```

## 故障排除

### 常见问题

1. **容器启动失败**
   ```bash
   # 查看详细错误信息
   docker-compose logs sms-forwarder

   # 检查配置文件
   docker-compose config
   ```

2. **端口被占用**
   ```bash
   # 检查端口占用
   netstat -tlnp | grep 12152

   # 修改端口（在 docker-compose.yml 中）
   ports:
     - "12153:12152"  # 使用不同的外部端口
   ```

3. **通知发送失败**
   ```bash
   # 检查服务状态
   curl http://localhost:12152/status

   # 查看详细日志
   docker-compose logs -f sms-forwarder

   # 测试网络连接
   docker-compose exec sms-forwarder curl -I https://ntfy.sh
   ```

4. **配置文件问题**
   ```bash
   # 验证 YAML 语法
   python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

   # 重新生成配置
   cp config.example.yaml config.yaml
   ```

### 性能优化

1. **资源限制调整**
   ```yaml
   # docker-compose.yml
   deploy:
     resources:
       limits:
         memory: 512M  # 增加内存限制
         cpus: '1.0'   # 增加 CPU 限制
   ```

2. **日志轮转**
   ```yaml
   # docker-compose.yml
   logging:
     driver: "json-file"
     options:
       max-size: "10m"
       max-file: "3"
   ```

## 更新和维护

### 更新应用

```bash
# 1. 拉取最新代码
git pull

# 2. 重新构建和部署
./scripts/deploy.sh

# 或手动更新
docker-compose build --no-cache
docker-compose up -d
```

### 定期维护

```bash
# 清理未使用的 Docker 资源
docker system prune -f

# 查看磁盘使用
du -sh logs/ data/ gotify_data/

# 备份重要数据
./scripts/backup.sh  # 如果有备份脚本
```