Warren
55bca92691
Core features: - Class 1 T.30 protocol: full send/receive implementation - HDLC: DLE-stuffing, FCS strip, USR5637 bit-reversal handling - T.4 MH encoder/decoder (1728px A4 standard) - Document pipeline: PDF (Ghostscript), PNG, TIFF input - Width clamping: US Letter 1734px → 1728px fax standard - Cover page: CJK rasterization (TW/CN/JP/EN), TIFF + HTML output - OCR verification: Tesseract 5 with eng+chi_tra, CJK space-tolerant - API server (axum): health, send, jobs, cover, retry, cancel - Background worker: auto-poll queue, speed fallback, retry policy - Modem detection, pool management Real-world test results (2026-07-23): - V90 → 25153038: 4 pages, V.17 12000 bps, 2:33 ✅ - USR5637 → 25153038: 4 pages, V.17 12000 bps, 2:26 ✅ - Both faxes confirmed received on remote machine Tested: loopback (100% pixel match), multi-page, all input formats, cover pages, OCR verify, API endpoints, worker processing. 13 unit tests pass, 0 new clippy warnings.
346 lines
6.4 KiB
Markdown
346 lines
6.4 KiB
Markdown
# 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` |