跳轉到

tapioctl 指令參考

tapioctl 是 Tapio 的單一操作入口 — daemon 生命週期、交易日切換、盤前處理、巡檢 都在這裡。

指令結構

tapioctl <verb> [<daemon>] [args...]

全部 subcommand 一覽

<name> 可用值：core | quote-receiver | live-sync | mail | taifex-fetcher

指令 用途
tapioctl start <name> 啟動指定 daemon
tapioctl stop <name> 停止指定 daemon
tapioctl restart <name> stop → start
tapioctl status [-v] 全 daemon 狀態表（running/stopped/crashed/never）
tapioctl ps 執行中 daemon 的 CPU 分配與執行時間
tapioctl quote-clean 清 quote 暫存（stop quote-receiver 後才能跑）
tapioctl up rollover → preopen → 啟動所有 daemon
tapioctl down 停止所有 daemon
tapioctl log [<name>] [-f] [-g <pat>] 查 / 追 / grep 今日 log
tapioctl log ls 列出今日 log 目錄
tapioctl tail-all 同時追蹤所有 daemon 今日 log
tapioctl path <what> 印絕對路徑
tapioctl session 顯示 system_date、盤別、rollover 狀態
tapioctl version 版本號與組建資訊
tapioctl rollover 設定今日 system_date，建立當日目錄
tapioctl preopen 載入盤前設定檔（投資人設定、餘額、部位、費率）
tapioctl archive --older-than <N>d [--dry-run] 封存舊日資料（壓縮 + 刪原檔）
tapioctl keys rotate-expiring [--dry-run] [--threshold-days N] [--validity-days N] API Key 自動補發 / 換發（cron-driven）
tapioctl list broker 設定與可用 subcommand
tapioctl dump kinds <KIND>... 解析今日產品檔，dump 指定商品的欄位
tapioctl check <子檢查> 巡檢（pfiles / config / disk / logs / tcpdirect / all）
tapioctl --help 完整說明

Daemon 操作

所有 daemon 的 start / stop / restart / status 語意一致，只是對象不同。

start

tapioctl start core
tapioctl start quote-receiver
tapioctl start live-sync
tapioctl start taifex-fetcher
tapioctl start mail

將指定 daemon 作為背景程序啟動，確認存活後回傳。

重複執行：daemon 已在執行時，指令提示服務已在執行中並退出，不會自動 restart。
失敗時：回傳碼 2，終端機會顯示對應 log 的路徑。

回傳碼：0 成功；2 失敗。

stop

tapioctl stop core
tapioctl stop quote-receiver
...

送停止訊號給 daemon，等待其自行結束；超過 10 秒則強制終止。

重複執行：daemon 本就未執行時，視為成功，退出 0，不報錯。

restart

stop 後短暫緩衝再執行 start，行為等同於手動依序下 stop / start。

status

tapioctl status       # 簡要表格
tapioctl status -v    # 含 PID、啟動時間等詳細欄位

列出所有 daemon 當前狀態。可能狀態值：running、stopped、crashed、never。

輸出範例：

$ tapioctl status
NAME                   STATE     PID      UPTIME    RSS    LAST EXIT
core                   running   1095368  4h44m     404M   -
quote-receiver         running   1093558  7h22m     5M     -
live-sync              running   1095326  4h45m     14M    -
mail                   crashed   -        -         -      exit=2, 1d20h ago
taifex-fetcher         running   1093502  7h23m     9M     -
---
4/5 running, 1 crashed

$ tapioctl status -v
NAME                   STATE     PID      UPTIME    STARTED              RSS    LAST EXIT                BINARY
core                   running   1095368  4h46m     2026-04-23 09:09:01  404M   -                        tapio-core
quote-receiver         running   1093558  7h24m     2026-04-23 06:31:00  5M     -                        tapio-quote-receiver
live-sync              running   1095326  4h47m     2026-04-23 09:08:01  14M    -                        tapio-live-sync
mail                   crashed   -        -         -                    -      exit=2, 1d20h ago        tapio-mail
taifex-fetcher         running   1093502  7h25m     2026-04-23 06:30:01  10M    -                        tapio-taifex-fetcher
---
4/5 running, 1 crashed

重複執行：唯讀查詢，無副作用，可隨時執行。

回傳碼：0 全部 running；1 有 stopped/crashed；2 錯誤。

quote-clean

tapioctl quote-clean

清除行情快取資料。必須先執行 tapioctl stop quote-receiver，否則可能造成行情資料損壞。

重複執行：快取已清空時，再次執行無額外效果。

交易日 / 盤前

rollover

tapioctl rollover

設定 system_date 並建立當日所需的 log / storage 目錄。任何 daemon 啟動前必須先執行。

換日邊界：執行時間 ≥ 06:00 設為當日；< 06:00（凌晨段）設為前一日。夜盤結束後的維運作業仍在前一交易日範圍內執行，不會提前跳到新日期。

重複執行：system_date 已是目標日期且目錄已存在時，再次執行無副作用。

preopen（盤前檔轉檔）

tapioctl preopen [--force]

從 broker 投入的 *.TXT 原始檔載入盤前設定，任一步驟失敗立即中止，不會帶錯誤資料開盤。

執行流程：

  1. 從 preopen_src（Tapio.toml [preopen].source_dir）讀取 broker 投入的 *.TXT 原始檔
  2. 複製到 data/preopen/<system_date>/
  3. 依序執行四支 loader：
    • tapio-load-investor-setting — 投資人設定
    • tapio-load-balance — 保證金／餘額
    • tapio-load-position — 持倉
    • tapio-load-fee — 手續費
  4. 全部成功後寫入 .done marker

重複執行：當日 preopen 已完成時，再次執行會直接跳過（idempotent guard）。若需要在盤中重新投檔，加上 --force 強制重跑所有步驟。

重新載入後須重啟 core：preopen 只將資料寫入磁碟；core daemon 在啟動時才讀取這些設定。盤中重新投檔後，須執行 tapioctl restart core 才能讓新設定生效。

全域 daemon 操作

以下指令一次作用於所有受管 daemon，省去逐一下指令的步驟。

up / down

tapioctl up           # rollover → preopen → 啟動所有 daemon
tapioctl down         # 停止所有 daemon

up 依序執行 rollover、preopen，再啟動所有 daemon；任一步驟失敗即 abort。
down 同時送停止訊號給所有 daemon，超時則強制終止。

重複執行 up：已執行中的 daemon 不會被重啟（見 start 說明）；rollover 與 preopen 具備冪等性，目錄已存在或當日已完成投檔時再次執行無額外效果。
重複執行 down：未執行的 daemon 視為成功，無副作用。

ps

tapioctl ps

列出所有執行中 daemon 的 CPU 分配與執行時間。唯讀查詢，可隨時執行。

輸出範例：

    PID USER     %CPU %MEM   RSS PSR STAT     ELAPSED CMD
1093502 tapio     0.0  0.0 10224   6 Sl      07:43:49 /opt/Tapio/bin/tapio-taifex-fetcher --config /opt/Tapio/etc/Tapio.toml --program-root /opt/Tapio
1093558 tapio     2.9  0.0  4728  10 Sl      07:42:50 /opt/Tapio/bin/tapio-quote-receiver 192.168.2.26
1095326 tapio     0.0  0.0 14680  10 Sl      05:05:49 /opt/Tapio/bin/tapio-live-sync
1099412 tapio    96.2  2.5 413548  6 SLl        00:11 /opt/Tapio/bin/tapio-core

pid=1099412  affinity: 6
pid=1093558  affinity: 0-11
pid=1095326  affinity: 0-11
pid=1093502  affinity: 0-11

欄位說明（上半段）

欄位 說明
PID Process ID
%CPU CPU 使用率；tapio-core 接近 100 屬正常，核心熱迴圈以 spin-loop 持續輪詢以達低延遲，會占滿單核
%MEM 占系統總實體記憶體的百分比
RSS 實際占用的實體記憶體（KB）
PSR 上次被排程執行的 CPU 核心編號
STAT 程序狀態旗標：S 睡眠中、L 記憶體已鎖定（mlock，降低延遲抖動）、l 多執行緒；tapio-core 的 SLl 代表三者皆具
ELAPSED 程序已執行時間（HH:MM:SS）
CMD 執行路徑與參數

下半段 affinity

顯示各 process 允許排程的 CPU 核心範圍。affinity: 6 表示整個 process 被限制在核心 6；affinity: 0-11 表示未綁定特定核心。

tapio-core 是多執行緒程序（STAT 含 l），各 thread 可再各自 pin 到不同核心；此處顯示的是 process 層級設定，不反映個別 thread 的 CPU pinning。

Log 查看

log

tapioctl log <target> [選項]

<target> 可以是：

Target 說明
core tapio-core 主要 log
core-stdout tapio-core 啟動輸出
quote tapio-quote-receiver 輸出
live-sync tapio-live-sync 輸出
mail tapio-mail 輸出
taifex-fetcher tapio-taifex-fetcher 輸出
packet 封包擷取 log
ls 列出當日所有 log 檔

常用選項：

選項 說明
-f, --follow 持續追蹤（tail -f 模式）
-g <pattern>, --grep <pattern> 過濾含 pattern 的行

範例：

tapioctl log core -f                  # 即時追蹤 tapio-core 主要 log
tapioctl log core -g "ERROR"          # 只看 ERROR 行
tapioctl log core-stdout -f -g "WARN" # 追蹤啟動輸出並過濾 WARN
tapioctl log ls                       # 列出所有 log 檔

tail-all

tapioctl tail-all

同時追蹤所有 daemon 的 log，適合盤前確認各 daemon 啟動狀況。

路徑查詢 — tapioctl path

tapioctl path <key> [daemon]

印出指定路徑，方便 script 取用，不用 hardcode。

Key 說明
prefix 安裝根目錄
bin binary 目錄
run 執行狀態檔目錄
log log 根目錄（含日期子目錄）
log-current 當日 log 目錄
storage storage 根目錄
storage-current 當日 storage 目錄
data data 目錄
etc 設定檔目錄
config 主設定檔路徑
pid <daemon> 指定 daemon 的執行狀態檔路徑
today 當日 system_date（YYYYMMDD）

範例：

tapioctl path prefix          # /opt/Tapio
tapioctl path log-current     # /opt/Tapio/log/20260421
tapioctl path pid core        # /opt/Tapio/run/core.pid
tapioctl path today           # 20260421

Session / Version

tapioctl session   # 顯示 system_date、broker、安裝根目錄等當前 session 資訊
tapioctl version   # 顯示版本號與組建資訊

tapioctl version 輸出分四段：

tapioctl build-time 設定:
  broker:        SinoPac
  pollio_impl:   epoll

runtime 設定:
  program_root:  /opt/Tapio
  config:        /opt/Tapio/etc/Tapio.toml
  preopen_src:   /home/sinopac
  quote_ip:      192.168.2.26
  livesync_dir:  /home/sinopac
  mail_config:   /opt/Tapio/etc/Tapio.toml

RPM 套件:
  tapio-1.7.1-1.4.g07f3479.x86_64

binary 資訊（version=烤進 binary，安裝時間=檔案 mtime）:
  core             tapio-core                   23M     安裝 2026-05-29 16:46:05
                   └ v1.7.1-4-g07f3479 (built 2026-05-29 09:18:57)
  quote-receiver   tapio-quote-receiver         1.4M    安裝 2026-05-29 16:46:05
                   └ v1.7.1-4-g07f3479 (built 2026-05-29 09:18:57)
  live-sync        tapio-live-sync              22M     安裝 2026-05-29 16:46:05
                   └ v1.7.1-4-g07f3479 (built 2026-05-29 09:18:57)
  mail             tapio-mail                   4.9M    安裝 2026-05-29 16:46:05
                   └ v1.7.1-4-g07f3479 (built 2026-05-29 09:18:57)
  taifex-fetcher   tapio-taifex-fetcher         4.6M    安裝 2026-05-29 16:46:05
                   └ v1.7.1-4-g07f3479 (built 2026-05-29 09:18:57)
段落 內容
build-time 設定 編譯時寫入的固定值：broker 代號、IO 實作（epoll = 通用版；tcpdirect = 高速版）
runtime 設定 從設定檔與環境讀取的執行期參數：安裝路徑、設定檔位置、盤前來源目錄、報價 IP 等
RPM 套件 rpm -q tapio 的結果（套件名小寫 tapio）——目前主機上裝的是哪一包。整批 binary 一次裝同一個 RPM，這是「裝了哪一版」的權威來源。非 rpm 安裝時跳過
binary 資訊 各 daemon 的執行檔。version 是組建時烤進 binary 的 git 版本字串（每支跑 --version 取得，build 當下固定不變）；安裝時間 是檔案 mtime（install/copy 當下），只代表「這顆檔案何時放上去」，與程式版本無關，故兩者分開顯示

version 與安裝時間的差別

version 跟著原始碼走、安裝時間 跟著檔案放置動作走，兩者刻意分開。 若有人 touch 或重新複製過 binary，安裝時間 會變但 version 不變—— 要辨識「跑的是哪一版程式」一律看 version，不要看時間。 單一 binary 也可直接查：tapio-core --version。

封存 — tapioctl archive

tapioctl archive --older-than <N>d [--dry-run]

將距今 ≥ N 天的舊日資料（storage、log、盤前檔、期交所資料）壓縮成單一封存檔，壓縮成功後刪除原檔。

安全限制：

  • --older-than 最小值為 2（今天與昨天永遠保留）
  • system_date 未設定時立即中止，不以系統時間替代

重複執行：已封存的日期不會重複處理。上次執行若中途失敗，殘留的暫存檔會在下次執行時自動清除並重試。

回傳碼：0 成功（含無候選）/ 1 部分日失敗 / 2 參數錯誤或 system_date 未設。

操作步驟（dry-run 預覽、執行壓縮、移至 NAS）詳見定期操作 → 日誌檔壓縮歸檔。

API Key — tapioctl keys

tapioctl keys rotate-expiring [--dry-run] [--threshold-days N] [--validity-days N]

對全體使用者執行一輪 API Key 換發，預期由 cron 每日觸發。處理兩種情況：

  1. 使用者沒有任何 API Key：自動產生一把並寄信給該使用者。
  2. 既有 Key 將在門檻內到期：產生一把新 Key 並寄信，原 Key 在到期前仍可使用，避免換發瞬間斷線。

未登記 email 的帳號會直接 skip。寄信失敗（mail spool I/O 錯）只記 log 不重試 —— Key 已落盤，可改用其他工具補寄。

旗標：

Flag 預設 用途
--dry-run — 印出「將會做什麼」但不實際產生新 Key
--threshold-days N 90 剩餘天數 ≤ N 即視為將到期，需換發
--validity-days N 365 新 Key 的效期；必須大於 --threshold-days

回傳碼：

Exit 意義
0 admin gRPC 可達且使用者清單非空（per-acno 失敗只記 log，不影響 exit code）
非 0 admin gRPC 不可達，或使用者清單為空（snapshot 未載入）

cron 排程範本見crontab 範本 → API Key 自動補發 / 換發。

巡檢 — tapioctl check

子檢查 內容 失敗對策
pfiles 期交所產品檔齊全且格式正確 先查 taifex-fetcher log 判斷原因（見下方）
config 主設定檔可正常讀取 檢查並修正 /opt/Tapio/etc/Tapio.toml，修改後再跑一次確認
disk 磁碟使用率（≥80% 警告、≥95% 失敗） 清 log 或擴容
logs 檢查主 log 最後寫入時間（盤中間隔 < 10 分鐘為通過），判斷結果僅供參考 Tapio 可能掛了，找開發
tcpdirect TCPDirect 套件與核心模組已就緒 重新安裝 / 重載模組 / 重 build
all 跑以上所有 —

pfiles 失敗：判斷原因

cat /opt/Tapio/log/current/stdout/taifex-fetcher.log

依 log 內容判斷：

  • SFTP 連線失敗或拉檔中斷 → 找交易室確認 SFTP 帳密與連線，或手動補檔
  • 檔案已拉回但格式錯誤 → 找開發確認

回傳碼：0 通過 / 1 警告 / 2 失敗。

tapioctl check all
echo "exit code: $?"

詳見 故障排除 → tapioctl check。

list — 系統資訊

tapioctl list

一次印出當前環境的完整快照，適合部署後確認設定與 binary 均就緒。輸出分四段：

段落 內容
上方設定欄位 broker、IO 實作、路徑、system_date 等，與 tapioctl version 相同
受管 daemon 各 daemon 的啟動指令（含完整參數），start / stop / restart 實際執行的命令
binary 偵測 [Y] / [N] 逐一確認每支 binary 是否存在；新部署若有 [N] 表示安裝不完整
可用 subcommand 本環境支援的所有 tapioctl 指令，含用法提示

輸出範例：

broker:        SinoPac
pollio_impl:   epoll
program_root:  /opt/Tapio
config:        /opt/Tapio/etc/Tapio.toml
preopen_src:   /home/sinopac
quote_ip:      192.168.2.26
livesync_dir:  /home/sinopac
mail_config:   /opt/Tapio/etc/Tapio.toml
system_date:   20260423

受管 daemon:
  core                           /opt/Tapio/bin/tapio-core
  quote-receiver                 /opt/Tapio/bin/tapio-quote-receiver 192.168.2.26
  live-sync                      /opt/Tapio/bin/tapio-live-sync
  mail                           /opt/Tapio/bin/tapio-mail --config /opt/Tapio/etc/Tapio.toml
  taifex-fetcher                 /opt/Tapio/bin/tapio-taifex-fetcher --config /opt/Tapio/etc/Tapio.toml --program-root /opt/Tapio

binary 偵測:
  [Y] tapio-core                               core daemon (核心 Gateway)
  [Y] tapio-quote-receiver                     quote-receiver (行情接收)
  [Y] tapio-live-sync                          live-sync (盤中 balance/position 同步；per-broker optional)
  [Y] tapio-mail                               mail (API key 寄送；optional，不是每家 broker 都用)
  [Y] tapio-taifex-fetcher                     taifex-fetcher (Go 期交所 SFTP 拉檔；非 idempotent，rollover 後重啟)
  [Y] tapio-load-investor-setting              盤前 - 投資人設定
  [Y] tapio-load-balance                       盤前 - 餘額
  [Y] tapio-load-position                      盤前 - 部位
  [Y] tapio-load-fee                           盤前 - 手續費

可用 subcommand:
  up | down
              全體 daemon lifecycle（bulk；up 會 run rollover + preopen）
  start <name> | stop <name> | restart <name>
              單一 daemon lifecycle
  ...

注意：沒有 bulk restart — 要全部重開打 `tapioctl down && tapioctl up`。

dump — 產品檔欄位

tapioctl dump kinds <KIND>...

解析今日 data/taifex/<system_date>/ 的期交所產品檔（P08 / P09 / P13 / P14），dump 指定商品代號（3 碼，如 TXF / MXF / TMF / TXO）的欄位內容，涵蓋 4 個 systemType（日盤期貨 .20 / 夜盤期貨 .21 / 日盤選擇權 .10 / 夜盤選擇權 .11）。

常見排查情境：

# core log 出現 GW_UNSUPPORTED_SYMBOL_TEXT(MXFD6)，確認商品是否已在產品檔中
tapioctl dump kinds MXF | grep -a 'prodId=MXF'

# 盤前掃所有期貨主力商品的 margin 與部位限額
tapioctl dump kinds TXF MXF TMF

回傳碼：

Exit 意義
0 所有指定 kind 都讀到資料
非 0 某個 kind 整組檔案沒記錄（kind 拼錯或產品檔未更新），或 expected 檔案不存在

詳見 目錄與 log 配置。