期交所產品檔來源：pull 與 relay 模式¶

tapio-taifex-fetcher 負責把當日期交所產品檔（P06/P07/P08/P09/P13/P14 等）放進 /opt/Tapio/data/taifex/$today/，core 再從這個目錄載入。檔案怎麼進到這個目錄，有兩種模式：

模式	檔案來源	適用情境
`pull`（預設）	daemon 主動連 TAIFEX SFTP 拉檔	我方有 TAIFEX SFTP 存取權
`relay`	broker 從別台機器 SFTP push 到本機目錄，daemon 在本地輪詢轉入	broker 不開放我方存取 TAIFEX，改由 broker 投檔

flowchart LR
    subgraph pull [pull 模式]
        T[TAIFEX SFTP] -->|daemon 連出去拉| D1["data/taifex/$today/"]
    end
    subgraph relay [relay 模式]
        B[broker 機器] -->|SFTP push| R["relay_dir<br/>/home/sinopac/taifex"]
        R -->|daemon 本地輪詢 + 轉入| D2["data/taifex/$today/"]
    end

兩模式下游完全相同

不論 pull 或 relay，落地目錄 data/taifex/$today/、_history/ 封存、prior-day backfill、heartbeat、core 的載入路徑都一樣。只有「檔案怎麼進落地目錄」不同。 切換模式不影響 core，也不需要改 core 設定。

何時改用 relay¶

當 broker（例如永豐）不再開放我方直接存取 TAIFEX SFTP，改成由 broker 主動把檔案 SFTP push 到我們這台機器時，就改用 relay 模式收檔。

relay 模式設定步驟¶

1. 建立 push 落地帳號與目錄（OS 層）¶

broker 會用一個專屬 SFTP 帳號登入本機投檔。建議用 chroot 限制該帳號只能寫投檔目錄。

# 建專屬帳號（無 shell login）
sudo useradd -m -d /home/sinopac -s /usr/sbin/nologin sinopac

# chroot 規定：chroot 根目錄必須 root 所有、且不可 group/world 可寫
sudo chown root:root /home/sinopac
sudo chmod 755 /home/sinopac

# 實際投檔目錄掛在 chroot 根下，由 sinopac 帳號寫入
sudo mkdir -p /home/sinopac/taifex
sudo chown sinopac:sinopac /home/sinopac/taifex

sshd_config 加上 SFTP-only chroot（修改後 systemctl restart sshd）：

Match User sinopac
    ChrootDirectory /home/sinopac
    ForceCommand internal-sftp
    AllowTcpForwarding no
    X11Forwarding no

落地目錄路徑：chroot 內 vs daemon 看到的

chroot 後 broker 端看到的路徑是 /taifex（chroot 根之內）；daemon 是用一般 process 跑、不在 chroot 內，看到的是完整路徑 /home/sinopac/taifex。 relay_dir 要填 daemon 看到的完整路徑。

2. 開放 daemon 讀取權限¶

tapio-taifex-fetcher 以 tapio 帳號執行，需要能讀 /home/sinopac/taifex。用 ACL 給 tapio 讀取與遍歷權限（含對新檔生效的 default ACL）：

sudo setfacl -m u:tapio:x /home/sinopac
sudo setfacl -R -m u:tapio:rX /home/sinopac/taifex
sudo setfacl -d -m u:tapio:rX /home/sinopac/taifex   # broker 之後 push 的新檔自動帶上

驗證：

sudo -u tapio ls /home/sinopac/taifex

3. 改設定檔¶

/opt/Tapio/etc/Tapio.toml 加上 [fetcher] 段：

[fetcher]
mode = 'relay'
relay_dir = '/home/sinopac/taifex'
scan_interval_sec = 5
stable_ticks = 2

relay 模式不需要 [sftp]

relay 不連外，[sftp] 與 [system].nameservers 都用不到，可留著（會被忽略）也可清空。設定欄位細節見設定檔 → [fetcher]。

4. 重啟 daemon 並驗證¶

/opt/Tapio/bin/tapioctl stop taifex-fetcher
/opt/Tapio/bin/tapioctl start taifex-fetcher

log 第一行應顯示 relay 模式（不再是 sftp connected）：

INFO mode = relay; drop dir = /home/sinopac/taifex (scan 5s x 2 stable)

broker 投檔後，確認檔案有轉進落地目錄：

ls /opt/Tapio/data/taifex/$(cat /opt/Tapio/storage/system_date)/
/opt/Tapio/bin/tapioctl check pfiles

settle 機制與偵測延遲¶

SFTP put 是直接寫入（direct-write），檔案在傳輸途中會持續變大；若在寫到一半就轉入落地目錄，core 會讀到不完整的檔。relay 因此不會看到檔案就動，而是觀察每個檔的 (inode, size, mtime)，連續 stable_ticks 次掃描都沒變才視為投檔完成，再轉入落地目錄。

偵測延遲約為：

scan_interval_sec × stable_ticks   （預設 5 × 2 ≈ 5–10 秒）

bootstrap 檔在開盤前一次性投遞，這點延遲無影響。
盤中 reload（P08/P14 等）也非即時關鍵路徑，秒級延遲可接受。
要更快可調低 scan_interval_sec；但太低會增加無謂的目錄掃描，不建議低於 2 秒。

broker 投檔需求（須與 broker 確認）¶

relay 模式下檔案完全依賴 broker 投遞，以下要事先講好：

檔案全集：bootstrap 檔 P06、P07、P08、P09、P13、P14 一個都不能漏 — 少任何一個，core 開機會卡在 bootstrap gate 無法開盤。盤中檔（PA7/P39/T90/C01/P11/P19 等）也要一併投。
投檔時機：bootstrap 那組必須在每日清晨 core 重啟前到位（core 與 taifex-fetcher 的啟動時間見交易日作業流程）。
落地目錄固定：一律投到約定的 relay_dir（chroot 端看到的 /taifex）。
檔名格式：沿用期交所原始檔名（如 P08.10、C01.10.20260616...），daemon 以檔名前綴辨識種類。

broker 漏投時的安全網

daemon 啟動時會自動把前一日的 P08/P14 墊進今日落地目錄（prior-day backfill），所以 broker 偶爾漏投這兩個檔不會直接卡開盤 —— 但會用到昨日的舊值，仍應盡快補投。其餘 bootstrap 檔沒有這層保護。

切回 pull 模式¶

把 [fetcher].mode 改回 'pull'（或整段 [fetcher] 刪除，預設即 pull），確認 [sftp] 與 [system].nameservers 填妥，重啟 taifex-fetcher 即可。

排錯¶

daemon 日誌判讀（兩模式共用）見故障排除 → tapio-taifex-fetcher 日誌判讀。

log 卡在 mode = relay 後沒有 pulled / replaced → broker 還沒投檔，或檔案還在傳輸（尚未 settle）。確認 relay_dir 下有檔且大小已穩定。
relay ReadDir ...: permission denied → tapio 帳號讀不到 relay_dir。回到步驟 2 檢查 ACL。
check pfiles 顯示缺檔，但 relay_dir 內有該檔 → 檔名前綴不在白名單，或檔案一直在變動 settle 不了。比對檔名格式、確認 broker 投檔已結束。