跳至主要内容

安裝與部署

在 YouTube 開啟影片

安裝前必須從獨立可信來源核對封存檔 SHA256。不相符或沒有可信參考值時,STOP:不要解壓或執行安裝程式。

適用對象:PM(專案管理者)、IT 管理員,以及要自行安裝評估版的工程師。 安裝完成後的操作請看《isvn 使用手冊》。

0. 先選安裝方式

方式 A:專案安裝包 方式 B:Portable 評估版
誰來裝 PM,裝一次,成員共用 每個人裝在自己的家目錄
裝到哪裡 PM 選定的專案目錄(<安裝目錄>/bin) ~/.local/opt/isvn/<版本>
Subversion 使用系統已安裝的 svn 套件自帶 svn、svnadmin、svnmucc
Qt(GUI 需要) 不隨附,安裝時指定 Qt 路徑 不隨附,安裝時連到既有的 Qt
會不會初始化專案 會(執行 isvn admin init) 不會,只安裝程式
用途 團隊的正式專案 評估、教學、示範專案

兩種方式都不需要 root 或 sudo,也不會寫入系統路徑。

圖 I-01:兩種安裝方式的比較。

圖 I-01 兩種安裝方式的比較。


1. 系統總覽

isvn 以 SVN 保存所有版本的內容,在上面提供版本血緣(Lineage)、去重快取池(pool),以及以連結為基礎的工作區。一次部署有三個可以分開放置的位置,加上每位成員自己的工作區:

位置 內容 規模 建議
SVN repository 所有版本的內容,以 file:// 存取 大 IT 獨立掛載與擴充
Pool 去重後的工作檔案內容 大 IT 獨立掛載與擴充
專案目錄 共用設定與血緣資料庫(方式 A 也放程式) 小 放在 PM 的家目錄下即可
成員的工作區 各自 checkout 的版本 視工作量 各成員自行管理
  • 三個位置各自獨立,不需要在同一個目錄樹下。
  • pool 的容量由掛載的儲存空間決定;isvn 沒有「設定容量」的功能,擴容是加儲存空間。
  • pool 裡的 tmp/ 與 objects/ 必須在同一個檔案系統上(寫入時使用原子搬移)。把整個 pool 目錄放在同一個掛載點即可。

圖 I-03:一次部署的四個位置,以及它們之間的關係。

圖 I-03 一次部署的四個位置,以及它們之間的關係。


2. 系統需求

項目 需求
作業系統 Linux x86_64。Portable 評估版需要 glibc 2.34 以上,目標平台是 Ubuntu 24.04 與 Rocky Linux 9
Subversion 方式 A:系統要有 svn 用戶端,以及建立 repository 用的 svnadmin。方式 B:不需要,套件自帶
Qt 只有 GUI 需要:Qt 6.7.3(gcc_64)。Qt 不隨附;可以裝在任何位置,但安裝路徑與其中的 lib/、plugins/、qml/ 不可讓 group 或其他人寫入
圖形環境 GUI 需要 X11 桌面環境,以及 Qt 的 xcb 平台外掛所需的系統函式庫
SQLite 不需要另外安裝,程式已內含
專案 group 一個 Linux group(例如 prj_myproject),PM 與所有成員都要加入
權限 PM 要能建立目錄、設定 group 權限、建立 SVN repository;不需要 root
其他 python3 只有 TUT01 的 Demo Kit 會用到

3. 方式 A:專案安裝包

3.1 安裝包內容

isvn-installer/
  install.sh                  安裝程式(PM 執行)
  README.md
  bin/
    isvn                      CLI
    isvn-gui                  GUI 啟動程式(選用)
    libexec/isvn-gui          GUI 主程式(選用)
    libexec/isvn-gui.qt-version   GUI 建置時使用的 Qt 版本

bin/ 的內容來自 Release 建置的安裝結果(cmake --install <build> --prefix <暫存目錄>)。

交付前請確認: 原始碼庫中的 isvn-installer/bin/isvn 只是測試流程用的佔位檔,也沒有附 GUI。製作安裝包時,要換成實際建置出來的 CLI 與 GUI。

3.2 安裝前

  1. 建立專案 group,把 PM 與所有成員加進去。

  2. 建立 SVN repository(安裝程式不會代為建立):

    svnadmin create /data/svnrepos/myproject
    chgrp -R prj_myproject /data/svnrepos/myproject
    chmod -R g+rwX         /data/svnrepos/myproject
    
  3. 要使用 GUI 時,先安裝 Qt 6.7.3。

3.3 執行安裝

互動式,依提示輸入安裝目錄、repository、pool、group;安裝包含 GUI 時再輸入 Qt 路徑:

cd isvn-installer
./install.sh

非互動式:

./install.sh \
  --project-dir "$HOME/isvn/myproject" \
  --repo        file:///data/svnrepos/myproject \
  --pool        /cache/isvn_pool/myproject \
  --group       prj_myproject \
  --qt-prefix   /opt/Qt/6.7.3/gcc_64 \
  --yes
參數 說明
--project-dir 安裝目錄,也是專案目錄(ISVN_PROJECT_DIR)。程式與環境檔都裝在這裡
--repo SVN repository 的 file:// URL;必須已經存在,而且可以 svn list
--pool pool 的根目錄
--group 專案的 Linux group 名稱;必須已經存在
--qt-prefix GUI 使用的 Qt 路徑。省略時,安裝程式依序從環境變數 ISVN_QT_PREFIX、PATH 上的 qtpaths/qmake、CMAKE_PREFIX_PATH 與常見位置尋找,並以找到的第一個作為預設值
--yes 不再逐項確認

3.4 安裝程式做的事

  1. 檢查 svn、group 與 repository 是否可用。
  2. 複製 CLI 到 <安裝目錄>/bin/isvn。安裝包含 GUI 時:
    • 安裝 bin/isvn-gui 與 bin/libexec/isvn-gui;
    • 檢查 Qt 的版本與權限後,建立 bin/qt 連到 Qt 路徑。
  3. 產生 <安裝目錄>/isvn.cshrc 與 <安裝目錄>/isvn.bashrc,給成員 source。
  4. 執行 isvn admin init(見 3.5)。專案已經初始化過時會略過。
  5. 印出要提供給成員的指令。

GUI 一律用 isvn-gui 啟動,它從 bin/qt 找到 Qt,不需要設定 LD_LIBRARY_PATH。

3.5 admin init 做的事

isvn admin init \
  --project-dir "$HOME/isvn/myproject" \
  --repo        file:///data/svnrepos/myproject \
  --pool        /cache/isvn_pool/myproject \
  --group       prj_myproject
  • 建立專案目錄與其中的 .isvn/。
  • 建立血緣資料庫 .isvn/lineage.db,並記下最上層的 ROOT 節點。
  • 建立 pool 的結構:objects/、meta.db、locks/、tmp/、backup/。
  • repository 中還沒有 branches/ 時建立它。
  • 寫入 .isvn/config(repository、pool、group)。
  • 對以上目錄與檔案明確設定 group 與權限,不依賴 umask(數值見第 8 節)。

成功時印出 initialized isvn project at <專案目錄>。

重複執行是安全的:已經有 ROOT 紀錄時不會再記一次,只會檢查血緣的完整性。重新執行時會調整的項目見第 10 節。執行 admin init 的帳號就是這個專案的 PM。

3.6 更新程式或更換 Qt

  • 專案安裝包: 用新的安裝包、同樣的參數重新執行 install.sh。已初始化的專案會略過 admin init。更換 Qt 時改 --qt-prefix 即可。
  • 以 release slot 管理的環境(Production): 不要重跑安裝程式覆蓋,請依第 9 節的方式部署。

4. 方式 B:Portable 評估版

Portable 安裝包與 Terminux 共用 Qt;安裝包本身不含 Qt。

4.1 安裝

tar -xzf isvn-<版本>-linux-x86_64.tar.gz
cd isvn-<版本>-linux-x86_64
./install.sh --qt-dir /opt/Qt/6.7.3/gcc_64 --yes
  • --qt-dir 是 Qt 6.7.3 gcc_64 的根目錄(其下有 lib/libQt6Core.so.6)。省略時,安裝程式會嘗試沿用 Terminux 使用的 Qt。
  • 安裝到 ~/.local/opt/isvn/<版本>,並建立 ~/.local/opt/isvn/current 指向它。
  • 安裝程式會先核對套件內的檔案(Package SHA256SUMS: OK),再檢查 Qt 與系統函式庫。Qt 檢查通過之後才會把新版本設為 current。
  • 檢查沒過時會列出 [FAIL] 與缺少的函式庫名稱,而且不會安裝任何東西。
  • 同一個版本已經裝過時,會回報 already installed。
  • 安裝程式不會修改 PATH。

實際的輸出(Ubuntu 24.04 的全新帳號,Qt 掛載在 /opt/qt673):

圖 I-02:Portable 評估版的安裝、isvn-preflight 與 isvn version 的實際輸出。

圖 I-02 Portable 評估版的安裝、isvn-preflight 與 isvn version 的實際輸出。

4.2 檢查

ISVN_HOME="$HOME/.local/opt/isvn/current"
"$ISVN_HOME/isvn-preflight"
"$ISVN_HOME/isvn" version

isvn-preflight 的最後一行是 Ready. 才算安裝完成。出現 WARN no DISPLAY 只代表這個終端機沒有圖形環境,CLI 仍然可以使用。

4.3 使用

  • 一律透過 current/isvn、current/isvn-gui 與 current/svn/bin/ 下的工具啟動。直接執行 libexec/isvn 會跳過套件自帶的 Subversion。
  • GUI 只使用同一個安裝目錄中的 isvn。
  • Portable 評估版只安裝程式。要有專案可以操作,有兩個方法:
    • 用 TUT01 的 Demo Kit 建立示範專案(見 TUT01 的 Guide);

    • 自己建立一個練習用的專案與工作區:

      ISVN_HOME="$HOME/.local/opt/isvn/current"
      mkdir -p "$HOME/isvn_trial"
      "$ISVN_HOME/svn/bin/svnadmin" create "$HOME/isvn_trial/svnrepo"
      "$ISVN_HOME/isvn" admin init \
        --project-dir "$HOME/isvn_trial/project" \
        --repo        "file://$HOME/isvn_trial/svnrepo" \
        --pool        "$HOME/isvn_trial/pool" \
        --group       "$(id -gn)"
      "$ISVN_HOME/isvn" member init \
        --project-dir "$HOME/isvn_trial/project" \
        --workspace   "$HOME/isvn_trial/work"
      

      $HOME/isvn_trial 必須是還不存在的目錄名稱。完成後依第 6 節建立第一個版本。

圖 I-04 是同一組步驟實際執行的結果(為了讓指令短一點,先把 current 與 current/svn/bin 加進 PATH),最後列出 admin init 建立的目錄與權限:

圖 I-04:從零建立練習專案、工作區與第一個版本的實際輸出,以及 admin init 建立的權限。

圖 I-04 從零建立練習專案、工作區與第一個版本的實際輸出,以及 admin init 建立的權限。


5. 成員加入專案

多個帳號可以使用同一個專案,各自在自己的工作區中工作。每位成員依下列步驟加入。

圖 I-05:從安裝到開始使用:PM 做一次(上排),每位成員做一次(下排)。

圖 I-05 從安裝到開始使用:PM 做一次(上排),每位成員做一次(下排)。

5.1 確認 group

id -Gn          # 輸出中要有專案的 group

剛被加入 group 的帳號要重新登入才會生效。

5.2 設定環境(方式 A)

依自己的 shell source PM 提供的環境檔,建議寫進 ~/.cshrc 或 ~/.bashrc:

source <安裝目錄>/isvn.cshrc      # tcsh/csh
source <安裝目錄>/isvn.bashrc     # bash/sh

環境檔只做兩件事:把 <安裝目錄>/bin 加進 PATH,以及設定 ISVN_PROJECT_DIR。repository 與 pool 的位置由 .isvn/config 提供,成員不需要設定。

5.3 建立工作區

每位成員執行一次:

isvn member init \
  --project-dir <專案目錄> \
  --workspace   "$HOME/work/myproject"

member init 會:

  • 讀取專案的 .isvn/config;
  • 確認目前的帳號屬於專案 group,否則拒絕;
  • 確認 pool 可以使用(objects/、locks/、meta.db 都存在);
  • 確認 repository 可以連上;
  • 建立工作區目錄與 .isvn_local/,並記下專案目錄的位置。

成功時印出 initialized isvn workspace at <工作區>。

工作區根目錄本身不是 SVN 工作副本;之後取得的每個版本各自放在 <工作區>/<phase>/<block>/<stage>/<version>/。

5.4 開始使用

cd "$HOME/work/myproject"
isvn branches                               # 列出版本庫中的版本
isvn checkout trial/cpu/200_fe_datain/v2    # 取得一個版本
isvn-gui                                    # 開啟 GUI

GUI 第一次開啟時是「工作」頁;還沒有取得任何版本時,畫面如圖 U-06(《isvn 使用手冊》第 3.1 節)。

圖 U-06:第一次開啟 GUI:「工作」頁,工作區中還沒有任何版本。

圖 U-06 第一次開啟 GUI:「工作」頁,工作區中還沒有任何版本。


6. 建立第一個版本

repository 剛建立時沒有任何版本,isvn branches 的輸出是空的。第一個版本要明確指定沒有上游:

cd <工作區>
isvn create trial/cpu/000_datain/v1 --parent ROOT

完成時印出 created trial/cpu/000_datain/v1 from ROOT,新版本的工作副本在 <工作區>/trial/cpu/000_datain/v1/。

把設計檔案放進這個目錄後,用 GUI 的批次簽入,或 isvn checkin-batch 提交(見《isvn 使用手冊》第 9 節與第 19.1 節)。以兩個檔案 top.v、constraints.sdc 為例:

V=trial/cpu/000_datain/v1
plan_of() { python3 -c 'import json,sys; print(json.load(sys.stdin)["plan_hash"])'; }
plan=$(isvn checkin-batch preview $V --path top.v --path constraints.sdc --json | plan_of)
isvn checkin-batch apply $V --path top.v --path constraints.sdc --expected-plan "$plan" --message "initial design input" --json

輸出中的 "status":"committed" 與 revision 表示提交成功。

單一檔案或整個資料夾也可以用 isvn checkin <路徑> 提交(見《isvn 使用手冊》第 19.2 節)。


7. GC 排程

GC 由 PM 的帳號以 cron 執行。只有 PM(專案 .isvn 的擁有者)可以執行 isvn gc;其他帳號會被拒絕。

# 每小時:清除失效的連結紀錄,校正引用數(不回收空間)
0 * * * *  ISVN_PROJECT_DIR=/home/pm/isvn/myproject /home/pm/isvn/myproject/bin/isvn gc --reconcile

# 每天:使用率超過 90% 時回收空間,直到低於 70%
0 3 * * *  ISVN_PROJECT_DIR=/home/pm/isvn/myproject /home/pm/isvn/myproject/bin/isvn gc --reclaim --high 0.9 --low 0.7
  • cron 不會帶入你平常的環境,請寫出 isvn 的完整路徑,並設定 ISVN_PROJECT_DIR。上面的路徑是範例,請換成實際的安裝目錄。
  • 第一次排程之前,先手動執行 isvn gc --reconcile --dry-run 看看會清除什麼;它不會刪除任何東西。
  • 回收會先刪除沒有任何引用的內容。仍然不夠時,才會強制回收最久沒有使用的內容;這代表工作中的資料量接近 pool 的容量,是應該擴充儲存空間的訊號。用 isvn pool-stat --evict-events 觀察強制回收發生的頻率。

SVN authz(選用): isvn 不管理 SVN 的 path-based authz。團隊需要以 stage 劃分讀寫權限時,請直接在 SVN 設定。


8. 目錄結構與權限

以下的權限數值是安裝程式與 isvn 建立的結果。

8.1 專案目錄

<專案目錄>/                       2770
  bin/                           方式 A 才有:isvn、isvn-gui、libexec/、qt
  isvn.cshrc、isvn.bashrc        方式 A 才有:成員的環境檔(0644)
  .isvn/                         2770
    config                       0640   repository、pool、group
    lineage.db                   0660   血緣資料庫

8.2 SVN repository

/data/svnrepos/myproject/
  branches/                      每個版本對應 branches/<phase>/<block>/<stage>/<version>

8.3 Pool

/cache/isvn_pool/myproject/      2770
  objects/                       3770
    <hash 前兩碼>/                3770
      <hash>                     0440   內容物件,唯讀
  meta.db                        0660   物件與連結的紀錄
  locks/                         2770
  tmp/                           2770   寫入時的暫存區(要和 objects/ 在同一個檔案系統)
  backup/                        2770

8.4 成員的工作區

<工作區>/                         0750
  .isvn_local/                   0700   工作區的私有狀態,請勿手動修改
    config                       0600   專案目錄的位置
    workspaces                   0600   已取得的版本清單
    workspace_state              0600   LOCAL 檔案的紀錄
    editable_receipts/                  「設為可編輯」的憑證(使用後才出現)
    work_operations/                    進行中操作的紀錄(使用後才出現)
  <phase>/<block>/<stage>/<version>/    各版本的工作副本

8.5 權限的原則

  • 共用的位置(專案目錄、pool)都以專案 group 加上明確的權限控制,不依賴 umask。
  • pool 的內容物件是唯讀的,避免被誤改;要修改檔案必須先「設為可編輯」。
  • lineage.db 允許 group 寫入。血緣的可信度不是靠檔案唯讀,而是靠只增不改的紀錄、每筆紀錄的帳號,以及完整性檢查(isvn lineage verify)。
  • 血緣資料庫與 pool 的 meta.db 是分開的兩個檔案,不可混用。

9. Production 的部署與回復(給維護者)

Production 的程式不是用安裝程式覆蓋,而是以 release slot 管理:

圖 I-06:Production 的 release slot:部署與回復都是切換連結。

圖 I-06 Production 的 release slot:部署與回復都是切換連結。

  • <專案目錄>/bin 是一個連結,經由 <專案目錄>/.isvn_release_slots/current 指向目前啟用的 slot(.isvn_release_slots/slots/<名稱>/)。每個 slot 是一組不可分開的 CLI 與 GUI,加上檔案清單與雜湊(manifest.sha256、manifest.links)。
  • 部署是先把新的一組放進新的 slot,再一次切換連結;回復是切回先前的 slot。
  • 每個 slot 帶有自己的 qt 連結,指向部署時指定的 Qt 路徑。
  • 預設保留最新的 3 個 slot 作為回復目標。
# 來源是 Release 建置的安裝結果
cmake --install build-release --prefix build-release/stage

scripts/deploy_release.sh --dry-run                                   # 先預演
scripts/deploy_release.sh --deploy [--qt-prefix /opt/Qt/6.7.3/gcc_64] # 再部署

scripts/rollback_release.sh --slot <slot 名稱> --dry-run
scripts/rollback_release.sh --slot <slot 名稱> --rollback

scripts/check_production_identity.sh                                  # 核對 production 的版本與雜湊

規則:

  • 不要用 cp 逐一覆蓋 production 的 isvn 或 isvn-gui。
  • CLI 與 GUI 一定成對部署、成對回復。
  • 省略 --qt-prefix 時,沿用目前 slot 的 Qt 路徑。
  • 每次部署與回復都要記錄在 docs/deployment/DEPLOYMENT_LOG.md,並更新 docs/deployment/production_identity.env。

詳細步驟見原始碼庫的 docs/deployment/ROLLBACK_SOP.md 與 docs/deployment/PRODUCTION_IDENTITY_GUARD.md。


10. 注意事項

  1. 重新執行 isvn admin init: 以相同的參數重新執行是安全的,不會動到 repository 的內容、血緣紀錄、pool 的內容與成員的工作區。它會做三件事:

    • 把專案目錄、.isvn 與 pool 根目錄的 group 設為 --group,權限設回 2770。如果你自己改過這三個目錄的權限(例如加上 sticky bit),重新執行之後要再改一次。
    • 依這一次指定的 --repo、--pool 與 --group 重寫 .isvn/config。手動加進這個檔案的內容不會保留。
    • repository 中沒有 branches/ 時建立它。

    不要用不同的 --repo 或 --pool 重新執行:專案會改為指向另一個 repository 或 pool,而既有的工作區不會跟著搬移。

  2. Qt 路徑的權限: Qt 的安裝路徑如果可以被 group 或其他人寫入,安裝程式與部署程式都會拒絕。


11. 驗證安裝

11.1 PM

isvn version                 # 確認 build
isvn lineage verify          # 應印出 Lineage integrity ok
isvn pool-stat               # 新專案:objects=0、refs=0
isvn admin status --json     # 三個位置的空間與權限摘要

11.2 成員

cd <工作區>
isvn workspaces              # 第一行是專案名稱;還沒有取得版本時沒有其他輸出
isvn branches                # 版本庫中的版本;新專案是空的

在工作區根目錄執行 isvn status 會提示要先進入某個版本的目錄,這是正常的。


12. 疑難排解

症狀 可能原因與處理
member init:current user is not in project group 帳號沒有加入專案 group。請管理員加入後重新登入,再用 id -Gn 確認
member init:pool is not initialized or not readable pool 沒有掛載,或權限不對。確認 objects/、locks/、meta.db 都存在,而且 group 可以存取
isvn: cannot locate project dir; set ISVN_PROJECT_DIR or run from a workspace 不在工作區內,也沒有設定 ISVN_PROJECT_DIR。source 環境檔,或進入工作區
isvn: not inside an isvn workspace; run isvn member init first 這個指令要在工作區內執行
寫入 pool 時搬移失敗 tmp/ 與 objects/ 不在同一個檔案系統。把整個 pool 放在同一個掛載點
isvn gc 回報 AUTHORIZATION_DENIED 只有 PM 可以執行 GC
isvn remove <資料夾> 回報 svn: E155011 … is out of date 資料夾中的檔案在資料夾取得之後又被提交過。先在該版本目錄執行 isvn update,再執行一次
pool 持續成長、空間不足 工作中的資料量大於容量。用 isvn pool-stat --evict-events 觀察;持續出現強制回收時協調 IT 擴充
isvn lineage verify 回報不完整 可能有人繞過 isvn 直接改動資料庫。用 isvn lineage audit 查看斷點附近的帳號與時間
GUI:refusing to start without its own isvn CLI GUI 的安裝目錄中沒有配對的 isvn。重新安裝完整的一組
GUI 啟動時找不到 Qt 函式庫 bin/qt(或 Portable 的 qt)沒有指向正確的 Qt 6.7.3。方式 A 用 --qt-prefix 重新安裝;方式 B 用 --qt-dir 重新安裝
Portable 的 install.sh:Qt check failed; nothing was installed Qt 路徑不對,或缺少系統函式庫。依 [FAIL] 那一行處理後重新執行