安裝與部署
安裝前必須從獨立可信來源核對封存檔 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 兩種安裝方式的比較。
1. 系統總覽
isvn 以 SVN 保存所有版本的內容,在上面提供版本血緣(Lineage)、去重快取池(pool),以及以連結為基礎的工作區。一次部署有三個可以分開放置的位置,加上每位成員自己的工作區:
| 位置 | 內容 | 規模 | 建議 |
|---|---|---|---|
| SVN repository | 所有版本的內容,以 file:// 存取 |
大 | IT 獨立掛載與擴充 |
| Pool | 去重後的工作檔案內容 | 大 | IT 獨立掛載與擴充 |
| 專案目錄 | 共用設定與血緣資料庫(方式 A 也放程式) | 小 | 放在 PM 的家目錄下即可 |
| 成員的工作區 | 各自 checkout 的版本 | 視工作量 | 各成員自行管理 |
- 三個位置各自獨立,不需要在同一個目錄樹下。
- pool 的容量由掛載的儲存空間決定;isvn 沒有「設定容量」的功能,擴容是加儲存空間。
- pool 裡的
tmp/與objects/必須在同一個檔案系統上(寫入時使用原子搬移)。把整個 pool 目錄放在同一個掛載點即可。

圖 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 安裝前
-
建立專案 group,把 PM 與所有成員加進去。
-
建立 SVN repository(安裝程式不會代為建立):
svnadmin create /data/svnrepos/myproject chgrp -R prj_myproject /data/svnrepos/myproject chmod -R g+rwX /data/svnrepos/myproject -
要使用 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 安裝程式做的事
- 檢查
svn、group 與 repository 是否可用。 - 複製 CLI 到
<安裝目錄>/bin/isvn。安裝包含 GUI 時:- 安裝
bin/isvn-gui與bin/libexec/isvn-gui; - 檢查 Qt 的版本與權限後,建立
bin/qt連到 Qt 路徑。
- 安裝
- 產生
<安裝目錄>/isvn.cshrc與<安裝目錄>/isvn.bashrc,給成員source。 - 執行
isvn admin init(見 3.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 的實際輸出。
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 建立的權限。
5. 成員加入專案
多個帳號可以使用同一個專案,各自在自己的工作區中工作。每位成員依下列步驟加入。

圖 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:「工作」頁,工作區中還沒有任何版本。
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:部署與回復都是切換連結。
<專案目錄>/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. 注意事項
-
重新執行
isvn admin init: 以相同的參數重新執行是安全的,不會動到 repository 的內容、血緣紀錄、pool 的內容與成員的工作區。它會做三件事:- 把專案目錄、
.isvn與 pool 根目錄的 group 設為--group,權限設回2770。如果你自己改過這三個目錄的權限(例如加上 sticky bit),重新執行之後要再改一次。 - 依這一次指定的
--repo、--pool與--group重寫.isvn/config。手動加進這個檔案的內容不會保留。 - repository 中沒有
branches/時建立它。
不要用不同的
--repo或--pool重新執行:專案會改為指向另一個 repository 或 pool,而既有的工作區不會跟著搬移。 - 把專案目錄、
-
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] 那一行處理後重新執行 |