定期操作¶

與交易日 lifecycle 無關、但需週期性執行的設定變更與維護作業。

更換 SFTP 帳號密碼¶

期交所定期要求更換 SFTP 憑證（taifex-fetcher 用此帳號拉取產品參數檔）。

建議時機：盤後（14:30 之後）或開盤前（06:30 之前），避免在 taifex-fetcher 拉檔期間中途換密碼。

步驟：

編輯 /opt/Tapio/etc/Tapio.toml，更新 [sftp] 區段：

[sftp]
username = 'new_user'
password = 'new_password'

確認設定檔語法正確：
```
tapioctl check config
```
重啟 taifex-fetcher：
```
tapioctl restart taifex-fetcher
```
確認連線成功 — log 出現 sftp connected 表示新帳密有效：
```
tail -f /opt/Tapio/log/current/stdout/taifex-fetcher.log
```
成功範例（節錄）：
```
2026/04/23 06:30:02.464582 INFO sftp connected to sftp1.test.taifex:22999
...
2026/04/23 07:10:45.434441 INFO pulled /F002/P07.20.F002 -> P07.20.F002 (5810 bytes)
2026/04/23 07:10:47.690490 INFO pulled /F002/P12.20.F002 -> P12.20.F002 (487760 bytes)
```
connection lost 是正常現象

期交所 SFTP 伺服器會定期斷線，taifex-fetcher 偵測到後會自動重連（log 出現 reconnecting，隨後再次出現 sftp connected）。重連成功後即恢復拉檔，無需人工介入。

盤中可以做嗎

taifex-fetcher 每次輪詢獨立建立連線，重啟後下一個輪詢週期即使用新帳密。盤中重啟不影響 core 或行情，風險極低；若需要在盤中處理，可直接執行，不必等到盤後。

更換 SMTP 設定¶

郵件 relay 主機、帳密或加密方式異動時，更新 [mail] 區段。

建議時機：任何時間均可 — tapio-mail 有本地 spool queue，重啟期間產生的告警信件會暫存，重啟完成後自動補送。

步驟：

編輯 /opt/Tapio/etc/Tapio.toml，更新 [mail] 區段：

[mail]
smtp_host = 'new-relay.internal'
smtp_port = 587
smtp_user = '[email protected]'
smtp_password = 'new_password'
smtp_security = 'starttls'

確認設定檔語法正確：
```
tapioctl check config
```
重啟 mail daemon：
```
tapioctl restart mail
```
驗證送信正常 — 請管理人員從管理介面重新發送一封信件測試，或等下一個告警事件觀察 log：
```
tail -f /opt/Tapio/log/current/stdout/tapio-mail.log
```

日誌檔壓縮歸檔¶

Tapio 的日誌與儲存資料依日期分目錄存放，定期壓縮並移至 NAS 可釋放本機磁碟空間。

建議時機：任何時間均可，壓縮對象為歷史目錄，不影響執行中的服務。

步驟¶

預覽候選日期（不實際壓縮）：

tapioctl archive --dry-run --older-than=2d

輸出範例：

archive dry-run: system_date=20260423 older-than=2d
  候選: 3 個
    20260419  45M (未壓縮)
    20260420  171M (未壓縮)
    20260421  86M (未壓縮)
  未壓縮合計: 301M（壓縮後視資料組成而定，不預估）
  未達年齡門檻（< 2d）: 20260422(1d)

確認候選日期符合預期後再執行。

執行壓縮：
```
tapioctl archive --older-than=4d
```
完成後確認輸出顯示「失敗 0」：
```
[tapioctl] archive: 完成 — 成功 1、skip(已存在/無資料) 0、失敗 0
```
壓縮檔產生於 /opt/Tapio/archived/，格式為 <日期>.tar.zst。
上傳給 broker（SFTP）：

tapioctl ship 透過 lftp 把 archived/*.tar.zst 全部送到 broker 指定的 SFTP，成功後本地檔自動 unlink（lftp put -E 語意：「成功就刪、失敗就留」）；失敗的檔保留在 archived/ 等下次 ship 自動重試（lftp 內建 net:max-retries=3）。

第一次使用前須完成設定封存上傳 SFTP 帳密（憑證放在 /opt/Tapio/etc/secret/ship-sftp.env，mode 必須 600）。
```
# 預覽要送的檔與遠端目的地，不實際發 lftp
tapioctl ship --proto sftp --dry-run

# 實際上傳
tapioctl ship --proto sftp
```
輸出範例（dry-run）：
```
ship dry-run: broker=SinoPac host=128.110.24.116 port=22
  候選: 3 個
    /opt/Tapio/archived/20260415.tar.zst
      → sftp://128.110.24.116/2604/20260415.tar.zst
    /opt/Tapio/archived/20260416.tar.zst
      → sftp://128.110.24.116/2604/20260416.tar.zst
    /opt/Tapio/archived/20260417.tar.zst
      → sftp://128.110.24.116/2604/20260417.tar.zst
```
完成後確認顯示「失敗 0」：
```
[tapioctl] ship: 完成 — 成功 3、失敗 0（host=128.110.24.116）
```
Remote 路徑由 broker 規則決定

SinoPac 規則：第一層為 YYMM（兩位西元年 + 兩位月），第二層為檔案。其他 broker 規則不同，由 RPM build-time 寫死在 tapioctl 內（一個 RPM 對應一個 broker）；要新增 broker 上傳支援需改 scripts/tapioctl.in 的 ship_remote_path() 並重出 RPM。

本地會被刪掉，cron 跑前先 dry-run 確認一次

tapioctl ship 不可逆 — 上傳成功的檔本地直接 unlink，重跑也不會回來（broker 那邊保留）。第一次部署或換 broker 後一定要先 --dry-run 看一眼路徑算對。

設定封存上傳 SFTP 帳密¶

tapioctl ship --proto sftp 第一次使用前必須建立 /opt/Tapio/etc/secret/ship-sftp.env。RPM 隨附 .example 範本，ops 須自行複製、填值、設權限。

建議時機：RPM 安裝完成後、第一次跑 tapioctl ship 之前。

步驟：

從範本複製：

sudo -u <operator> cp \
  /opt/Tapio/etc/secret/ship-sftp.env.example \
  /opt/Tapio/etc/secret/ship-sftp.env

填入 broker 提供的帳密：
```
sudo -u <operator> vim /opt/Tapio/etc/secret/ship-sftp.env
```
內容：
```
SFTP_USER=<broker-account>
SFTP_HOST=<host-or-ip>
SFTP_PORT=22
SFTP_PASS=<password>
```
密碼含特殊字元請用單引號

檔案以 sh source 載入。值含 $、`、\ 須單引號包起來：
```
SFTP_PASS='YA$Q@Wch!23'
```
目前不支援雙引號（"）— tapioctl ship 會 fail fast。

修正權限為 600（tapioctl ship 啟動時會驗證；非 600 直接 fail）：

sudo chmod 600 /opt/Tapio/etc/secret/ship-sftp.env
sudo chown <operator>:<operator> /opt/Tapio/etc/secret/ship-sftp.env

連線驗證 — --dry-run 不會真連 SFTP，但能確認檔案讀得到、欄位都填了：
```
sudo -u <operator> /opt/Tapio/bin/tapioctl ship --proto sftp --dry-run
```
若有檔案在 archived/ 內，會列出 host / port / 預計 remote 路徑。沒有檔也應印 ship: ... 沒有 *.tar.zst 可送，不該報 creds 相關錯。
真實連線測試 — 在沒有 archived 檔的視窗手動建一個小檔測試：
```
sudo -u <operator> dd if=/dev/zero of=/opt/Tapio/archived/$(date +%Y%m%d).tar.zst bs=1k count=1
sudo -u <operator> /opt/Tapio/bin/tapioctl ship --proto sftp
```
成功後本地檔會被 unlink；登進 broker SFTP 確認檔已到對的目錄。記得跟 broker 確認可否清掉測試檔。

換密碼時：

直接改 ship-sftp.env 的 SFTP_PASS 即可，無需重啟任何 daemon — tapioctl ship 每次執行都重新讀檔。建議在沒有 cron ship 排程的時段（例如剛跑完 ship 之後、下次 cron 之前）改，避免 cron 撞到改寫中途。