# Telfax 生產環境部署指南

## 系統需求

- macOS 10.14 或更新版本
- USB 數據機（已測試：V90, USR5637）
- 已安裝 Rust 工具鏈（用於編譯）
- 管理員權限（用於安裝服務）

---

## 快速部署（V90 Class 2）

### 1. 編譯發布版本

```bash
cd /path/to/telfax
cargo build --release
```

### 2. 安裝服務

```bash
sudo ./deployment/install-macos.sh
```

### 3. 配置服務

編輯配置文件：
```bash
nano /usr/local/etc/telfax/config.toml
```

**重要配置項：**

```toml
# 認證令牌（必須修改！）
[[auth.tokens]]
token = "your-secure-token-here"  # 修改為安全令牌
permissions = "admin"

# V90 數據機（Class 2 生產環境）
[[modems]]
device = "/dev/cu.usbmodem123456781"  # 確認設備路徑
name = "V90-Primary"
class = 2  # 使用 Class 2（穩定）
priority = 1
enabled = true
phone_number = "25289852"  # 設定電話號碼

# 傳真設定
[fax]
station_id = "+886-2-25289852"  # 設定傳真號碼
header = "Your Company Name"     # 設定公司名稱
default_class = 2                # 預設使用 Class 2
```

### 4. 啟動服務

```bash
# 載入服務
sudo launchctl load -w /Library/LaunchDaemons/com.telfax.server.plist

# 檢查狀態
sudo launchctl list | grep telfax

# 查看日誌
tail -f /usr/local/var/log/telfax/telfax.log
```

### 5. 測試 API

```bash
# 健康檢查
curl http://localhost:3000/health

# 查看狀態（需要認證）
curl -H "Authorization: Bearer your-secure-token-here" \
     http://localhost:3000/api/v1/status

# 查看數據機狀態
curl -H "Authorization: Bearer your-secure-token-here" \
     http://localhost:3000/api/v1/modems

# 查看 Prometheus 指標
curl http://localhost:9090/metrics
```

---

## 發送傳真測試

### 準備測試文件

```bash
# 創建測試封面頁
cat > test_cover.json <<EOF
{
  "to_name": "測試接收方",
  "to_number": "25153038",
  "from_name": "Telfax 測試",
  "subject": "傳真測試",
  "message": "這是一封測試傳真"
}
EOF
```

### 發送傳真

```bash
# 發送傳真
curl -X POST http://localhost:3000/api/v1/fax/send \
  -H "Authorization: Bearer your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d @test_cover.json
```

### 查看任務狀態

```bash
# 列出所有任務
curl -H "Authorization: Bearer your-secure-token-here" \
     http://localhost:3000/api/v1/jobs

# 查看特定任務
curl -H "Authorization: Bearer your-secure-token-here" \
     http://localhost:3000/api/v1/jobs/{job_id}
```

---

## 接收傳真測試

### 檢查接收功能

1. 確保數據機已連接並啟用
2. 服務會自動接聽來電
3. 接收的傳真會存儲在 `/usr/local/var/lib/telfax/received/`

```bash
# 查看接收的傳真
ls -lh /usr/local/var/lib/telfax/received/

# 查看接收歷史
curl -H "Authorization: Bearer your-secure-token-here" \
     http://localhost:3000/api/v1/fax/received
```

---

## 監控與維護

### 日誌查看

```bash
# 即時日誌
tail -f /usr/local/var/log/telfax/telfax.log

# 錯誤日誌
tail -f /usr/local/var/log/telfax/telfax-error.log

# macOS 系統日誌
log show --predicate 'process == "telfax"' --last 1h
```

### Prometheus 監控

```bash
# 查看指標
curl http://localhost:9090/metrics

# 關鍵指標
# - telfax_fax_sent_total
# - telfax_fax_received_total
# - telfax_fax_failed_total
# - telfax_modem_status
# - telfax_job_queue_size
```

### 服務管理

```bash
# 停止服務
sudo launchctl unload /Library/LaunchDaemons/com.telfax.server.plist

# 重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.telfax.server.plist
sudo launchctl load -w /Library/LaunchDaemons/com.telfax.server.plist

# 檢查服務狀態
sudo launchctl list | grep telfax
```

---

## 故障排除

### 數據機無法連接

```bash
# 檢查設備路徑
ls -l /dev/cu.usbmodem*

# 檢查權限
ls -l /dev/cu.usbmodem123456781

# 測試連接
screen /dev/cu.usbmodem123456781 115200
# 輸入: ATI
# 應返回數據機信息
```

### 服務無法啟動

```bash
# 檢查配置文件
/usr/local/bin/telfax serve --config /usr/local/etc/telfax/config.toml

# 檢查權限
ls -l /usr/local/etc/telfax/config.toml
ls -l /usr/local/var/lib/telfax/
ls -l /usr/local/var/log/telfax/

# 檢查日誌
tail -n 50 /usr/local/var/log/telfax/telfax-error.log
```

### 傳真發送失敗

```bash
# 檢查數據機狀態
curl -H "Authorization: Bearer your-token" \
     http://localhost:3000/api/v1/modems

# 檢查任務佇列
curl -H "Authorization: Bearer your-token" \
     http://localhost:3000/api/v1/jobs

# 查看詳細日誌（調整日誌級別）
# 編輯 config.toml:
# log_level = "debug"
# 然後重啟服務
```

---

## 生產環境檢查清單

### 部署前

- [ ] 已修改所有認證令牌
- [ ] 已設定正確的 station_id 和 header
- [ ] 已確認數據機設備路徑
- [ ] 已測試基本發送/接收功能
- [ ] 已設定日誌輪轉
- [ ] 已設定備份策略

### 安全性

- [ ] 配置文件權限設為 600
- [ ] 使用強認證令牌（建議 32+ 字元）
- [ ] 考慮啟用防火牆規則
- [ ] 定期檢查訪問日誌
- [ ] 定期更新令牌

### 監控

- [ ] Prometheus 指標端點可訪問
- [ ] 日誌正常輸出
- [ ] 設定健康檢查
- [ ] 設定告警通知

### 備份

- [ ] 定期備份 `/usr/local/var/lib/telfax/`
- [ ] 定期備份配置文件
- [ ] 記錄令牌和安全配置

---

## 效能調優

### 數據機設定

```toml
[fax]
resolution = "fine"        # 高解析度
speed_fallback = true      # 啟用速率降級
default_class = 2          # 使用 Class 2（更穩定）
```

### 佇列設定

```toml
[queue]
max_retries = 3            # 最大重試次數
retry_intervals = [60, 300, 900]  # 重試間隔（秒）
```

### 監控設定

```toml
[monitoring]
metrics_port = 9090
enable_prometheus = true
health_check_interval = 60
```

---

## 升級

### 升級步驟

```bash
# 1. 停止服務
sudo launchctl unload /Library/LaunchDaemons/com.telfax.server.plist

# 2. 備份
sudo cp -r /usr/local/var/lib/telfax /usr/local/var/lib/telfax.backup
sudo cp /usr/local/etc/telfax/config.toml /usr/local/etc/telfax/config.toml.backup

# 3. 更新代碼
cd /path/to/telfax
git pull

# 4. 重新編譯
cargo build --release

# 5. 重新安裝
sudo ./deployment/install-macos.sh

# 6. 比對配置（如有更新）
# 手動合併配置變更

# 7. 重啟服務
sudo launchctl load -w /Library/LaunchDaemons/com.telfax.server.plist
```

---

## 支援

- 文檔：`docs/`
- 問題回報：GitHub Issues
- 配置參考：`deployment/config.production.toml`