telfax/docs/DEPLOYMENT.md

Telfax 生產環境部署指南

系統需求

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

---

快速部署（V90 Class 2）

1. 編譯發布版本

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

2. 安裝服務

sudo ./deployment/install-macos.sh

3. 配置服務

編輯配置文件：

nano /usr/local/etc/telfax/config.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. 啟動服務

# 載入服務
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

# 健康檢查
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

---

發送傳真測試

準備測試文件

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

發送傳真

# 發送傳真
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

查看任務狀態

# 列出所有任務
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/

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

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

---

監控與維護

日誌查看

# 即時日誌
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 監控

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

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

服務管理

# 停止服務
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

---

故障排除

數據機無法連接

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

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

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

服務無法啟動

# 檢查配置文件
/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

傳真發送失敗

# 檢查數據機狀態
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/
• 定期備份配置文件
• 記錄令牌和安全配置

---

效能調優

數據機設定

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

佇列設定

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

監控設定

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

---

升級

升級步驟

# 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