Web 安裝流程
透過二進位檔部署、Docker Compose 部署或 Kubernetes 部署啟動 Sayrud 後,開啟 http://server-address:2830/setup。尚未安裝時,開啟首頁也會重新導向此處。
安裝分為驗證身分、資料庫、管理員和完成四個步驟。頁面右上角可切換語言。
驗證身分
未指定安裝權杖時,程式會在啟動日誌中顯示 Setup token: 和含有權杖的安裝連結。將權杖複製到頁面,按一下「驗證」。遠端部署時,請將日誌連結中的 localhost 換成實際存取位址。
| 部署方式 | 查看日誌 |
|---|---|
| 前景執行 | 目前終端機 |
| systemd | sudo journalctl -u sayrud -n 100 --no-pager |
| Docker Compose | docker compose logs --tail=100 sayrud |
| Kubernetes | kubectl -n sayrud logs deployment/sayrud --tail=100 |
若已設定 SAYRUD_SETUP_TOKEN,請直接填入該環境變數的值。K8s 部署使用此方式,權杖保存在建立 Secret 時使用的本機檔案中。
自訂權杖移除空白與連字號後至少需有 16 個字元,可使用 openssl rand -hex 24 產生。驗證時會忽略大小寫、空白和連字號。
未固定權杖時,安裝期間重新啟動程序會產生新權杖,需要從最新日誌重新取得。權杖及含有權杖的連結只應交給負責安裝的人;建立管理員後,安裝介面會關閉。
設定資料庫
全新安裝時填寫以下資訊:
| 服務 | 欄位 |
|---|---|
| PostgreSQL | 主機、連接埠、資料庫名稱、使用者名稱、密碼、SSL 模式 |
| Redis | 主機:連接埠 格式的位址,以及選填的使用者名稱與密碼 |
連線由執行 Sayrud 的程序發起,與瀏覽器所在的電腦無關。Docker Compose 設定使用 postgres 和 redis:6379;K8s 使用叢集內的 Service 名稱或可存取的外部網域。
PostgreSQL 的 SSL 模式包括「不加密」「加密連線」「加密並驗證 CA 憑證」「加密並驗證憑證與主機名稱」。請依資料庫服務要求選擇;使用憑證驗證時,執行環境也需要信任對應的 CA。
按一下「測試連線」,確認 PostgreSQL 和 Redis 都顯示連線成功,再按一下「儲存並繼續」。
建立管理員
填寫電子郵件、使用者名稱、密碼和確認密碼,再按一下「完成安裝」。
這裡建立的是首位系統管理員,建立成功後會自動登入,按一下「開始使用」進入應用程式。
安裝完成後,確認可以建立專案、編輯記錄和上傳附件,並依部署方式檢查設定與上傳檔案是否已持久保存。網站設定、註冊開關、登入方式和 AI 模型等可在管理後台調整。
預先提供設定
若由設定管理系統提供連線資訊,可以預先準備 sayrud.yaml。以下為本機儲存的設定,請先替換連線密碼和 auth.secret_key:
postgres:
dsn: "postgres://sayrud:[email protected]:5432/sayrud?sslmode=disable"
redis:
address: "127.0.0.1:6379"
username: ""
password: ""
auth:
secret_key: "REPLACE_WITH_BASE64_KEY"
storage:
type: local
local:
path: ./data/storage使用以下命令產生 auth.secret_key,將完整輸出填入設定:
openssl rand -base64 32手動編寫 PostgreSQL URL 時,密碼中的 @、:、/ 等特殊字元需要做 URL 編碼。透過安裝精靈填寫時,程式會處理編碼。
將檔案放在啟動參數指定的位置,完整選項請參閱設定範例。變更設定後需要重新啟動程式。
常見問題
沒有出現安裝頁
若日誌顯示啟動成功,且資料庫已有使用者,程式會直接提供應用程式頁面,使用既有帳號登入即可。
安裝權杖失效
檢查安裝過程中是否重新啟動了程序。未設定 SAYRUD_SETUP_TOKEN 時,請使用最新日誌中的權杖。K8s 請先確認 Pod 使用了預期的 Secret,並在首次安裝時保持單副本。連續輸入錯誤權杖會觸發速率限制,請先核對權杖再重試。
資料庫測試失敗
檢查資料庫是否已建立、帳號密碼是否正確,以及應用程式所在主機或 Pod 能否存取目標位址。容器中的 127.0.0.1 指向容器本身。若連線成功但儲存失敗,也需檢查資料庫帳號是否有結構遷移權限。
全新安裝精靈會拒絕接管已有使用者的資料庫。還原既有執行個體時,應還原原始設定、金鑰和上傳檔案,依正常啟動流程連線至原資料庫,不要重新執行資料庫設定步驟。
儲存設定時出現權限錯誤
安裝精靈會先在設定目錄寫入暫存檔,再提交為 sayrud.yaml,因此目錄本身必須可寫入。檢查是否使用唯讀掛載、ConfigMap、Secret,或 UID/GID 與卷的擁有者不符。Docker 和 K8s 映像檔使用 10001:10001。
提示設定已儲存,但需要重新啟動
檢查服務日誌,排除後續服務初始化失敗的原因,再使用相同設定路徑重新啟動。已寫入的設定會重新載入,無須刪除檔案重新安裝。
重建容器後又出現安裝頁
檢查設定目錄是否掛載到 /home/app/config、是否仍使用原本的 PostgreSQL 資料庫,以及 Compose 專案名稱或 K8s PVC 是否變更。請先找回原始設定和資料,不要在新的安裝精靈中覆蓋原部署。