V1.0: Class 1 fax — real-world 4-page send to external number confirmed
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.
This commit is contained in:
Warren
@@ -0,0 +1,346 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user