核心環境變數
本頁收錄部署與日常運維會實際改動的環境變數:服務監聽、資料庫、金鑰、限額、外部服務對接、Compose 編排層與沙箱 sidecar。控制系統內部行為(併發、重試、批次大小、讀迴圈節奏等)的調優項不在本頁,見高階調優環境變數。
使用官方 Docker Compose 部署時,絕大多數變數已經由 compose 檔案填好合理值,你通常只需要在 .env 裡提供三個必設項:POSTGRES_PASSWORD、REDIS_PASSWORD、JWT_SECRET。本頁其餘變數按需查閱即可。
所有時長類變數(如 ACCESS_TTL、REFRESH_TTL)使用 Go duration 格式:數字加單位字尾,支援 s(秒)、m(分鐘)、h(小時),可以組合(如 1h30m)。沒有 d(天)單位,30 天要寫成 720h。
1. 服務基礎
| 變數 | 預設值 | 說明 |
|---|---|---|
AIVORY_LISTEN | :8787 | 服務監聽地址。預設監聽所有網絡卡的 8787 埠;只想繫結本機時可寫 127.0.0.1:8787。 |
AIVORY_ENV | development | 執行環境標識。設為 production 等非 dev 值後會觸發部署級安全校驗(見下文 JWT_SECRET 的啟動規則)。 |
STATIC_DIR | (空) | 指向已構建的 SPA 前端目錄時,API 程序會在同一埠同源伺服前端頁面。生產映象已內建該目錄,無需設定。 |
怎麼選/常見坑:生產部署務必把 AIVORY_ENV 設為 production,否則一部分只在部署環境生效的安全校驗不會啟用。STATIC_DIR 只在你自行構建前端、且想讓 API 程序直接託管靜態檔案時才需要;用官方映象時不要動它。前端與 API 同源(單容器同時服務 SPA 和 /api)是推薦形態,能省去跨域配置。
2. 資料庫與快取
| 變數 | 預設值 | 說明 |
|---|---|---|
DATABASE_URL | ./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000) | 資料庫連線串。預設是 SQLite 檔案路徑(帶 WAL 與 busy_timeout 引數);以 postgres:// 開頭時切換為 PostgreSQL。 |
REDIS_URL | (空) | Redis 連線串。留空時使用程序內快取與佇列;設定後啟用 Redis 快取、任務佇列與流式恢復。 |
QDRANT_URL | (空) | Qdrant 向量庫地址。留空時停用向量檢索,RAG 走全文注入回退。 |
QDRANT_API_KEY | (空) | 訪問 Qdrant 的 API key,與 Qdrant 服務端配置一致即可。 |
DATABASE_URL 的兩種形態示例:
# SQLite(單機小規模,詳見 SQLite 模式文件)
DATABASE_URL="./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"
# PostgreSQL(compose 部署預設形態)
DATABASE_URL="postgres://aivory:你的密碼@postgres:5432/aivory"
DATABASE_URL 是否為 postgres:// 字首,同時也是「是否為部署環境」判定的輸入之一:一旦連線 PostgreSQL,啟動時就會強制要求 JWT_SECRET(見下節)。另外,SQLite 與 PostgreSQL 之間沒有自動資料遷移,切換前請先通過備份與遷移匯出資料。
怎麼選/常見坑:單人或小團隊自用可以走 SQLite 模式,零外部依賴;多使用者生產環境建議 PostgreSQL + Redis + Qdrant 全套(compose 預設即此)。REDIS_URL 留空時流式恢復等依賴佇列的能力退化為程序內實現,多副本部署時必須配置 Redis。QDRANT_URL 留空並不影響知識庫功能可用,只是檢索質量退化為全文注入,文件量大時效果和 token 消耗都會變差。
3. 安全與會話
| 變數 | 預設值 | 說明 |
|---|---|---|
JWT_SECRET | (空) | 簽發訪問/重新整理令牌的金鑰。啟動校驗規則見下方警告。 |
ACCESS_TTL | 30m | 訪問令牌有效期,Go duration 格式。 |
REFRESH_TTL | 720h | 重新整理令牌有效期,預設 720 小時即 30 天。 |
ALLOWED_ORIGINS | http://localhost:5173,http://127.0.0.1:5173 | 允許跨域訪問 API 的 origin 白名單,逗號分隔。僅前後端分離部署需要;單容器同源部署無需設定。 |
開發環境下未設定 JWT_SECRET 時,服務會自動生成一個隨機臨時金鑰,每次重啟都會導致全部登入會話失效。當系統「看起來是部署環境」(AIVORY_ENV 非 dev 值,或 DATABASE_URL 是 PostgreSQL)時,必須顯式設定一個不少於 32 字元的金鑰,否則服務拒絕啟動。生成方式示例:
openssl rand -base64 48
金鑰一旦投產不要隨意更換:更換後所有使用者的登入態立即失效。
怎麼選/常見坑:ACCESS_TTL 調短能降低令牌洩露的視窗,但會增加重新整理頻率;REFRESH_TTL 決定使用者「多久沒來需要重新登入」。ALLOWED_ORIGINS 是新手常踩的坑:同源部署(推薦)完全不用配;只有把前端單獨部署到另一個域名時才需要把該前端 origin 加進來,寫完整的 scheme://host[:port],不要帶路徑和末尾斜槓。
4. 儲存與限額
| 變數 | 預設值 | 說明 |
|---|---|---|
UPLOAD_DIR | ./data/uploads | 使用者上傳檔案的存放目錄。 |
ARTIFACT_DIR | ./data/artifacts | 生成產物(程式碼執行輸出檔案等)的存放目錄。 |
BACKUP_DIR | ./data/backups | 備份檔案的存放目錄。 |
MAX_UPLOAD_BYTES | 52428800 | 單檔案上傳硬上限,預設 50MB。管理員後臺還可在此上限內按圖片/檔案分別收緊。 |
MAX_BACKUP_BYTES | 21474836480 | 備份匯入的大小上限,預設 20GiB。 |
DAILY_MESSAGE_LIMIT | 200 | 每使用者每日訊息條數上限。 |
IMAGE_DAILY_LIMIT | 30 | 每使用者每日圖片生成次數上限。 |
怎麼選/常見坑:三個目錄預設都在 ./data 下,compose 部署時對應宿主機的 DATA_DIR 掛載卷,請確保該卷有足夠磁碟空間並納入備份策略。MAX_UPLOAD_BYTES 是服務端硬上限,管理後臺的圖片/檔案限額只能比它更小,不能放大;如果調大這裡,還要同步調大反向代理的請求體上限(如 Nginx 的 client_max_body_size),否則請求會先被代理攔下,見反向代理。DAILY_MESSAGE_LIMIT 與 IMAGE_DAILY_LIMIT 是全域性預設,針對單個使用者的配額調整在使用者與配額裡操作。
5. 外部服務
| 變數 | 預設值 | 說明 |
|---|---|---|
SEARCH_PROVIDER | (空) | 聯網搜尋後端,如 serper。也可以在管理後臺配置。 |
SEARCH_API_KEY | (空) | 搜尋後端的 API key。 |
SEARCH_BASE_URL | (空) | 搜尋後端的自定義地址(自建或代理閘道器時使用)。 |
EMBEDDING_BASE_URL | (空) | 嵌入(embedding)服務的 API 地址,OpenAI 相容介面。 |
EMBEDDING_API_KEY | (空) | 嵌入服務的 API key。 |
EMBEDDING_MODEL | text-embedding-3-small | 嵌入模型名稱。 |
EMBEDDING_DIM | 1536 | 嵌入向量維度。 |
MINERU_API_URL | (空) | MinerU 服務地址,用於掃描版 PDF 的 OCR 解析。compose 裡預設填 https://mineru.net。 |
MINERU_API_KEY | (空) | MinerU 的 API key。 |
SANDBOX_BASE_URL | (空) | 程式碼沙箱 sidecar 的地址。compose 裡預設 http://sandbox:8000。 |
SANDBOX_API_KEY | (空) | 與沙箱 sidecar 通訊的共享金鑰。compose 裡預設使用共享值 aivory-bundled-sandbox。 |
ENABLE_MOCK_PROVIDER | false | 由 compose 傳入,啟用內建演示模型(無需真實模型 API 即可體驗介面)。 |
向量庫集合按固定維度建立,EMBEDDING_DIM 與 EMBEDDING_MODEL 實際輸出維度不一致時向量寫入與檢索都會出錯。更換嵌入模型時務必同步修改該值,且已入庫的舊向量與新維度不相容,需要重建知識庫索引。預設的 text-embedding-3-small 對應 1536 維。
怎麼選/常見坑:搜尋與嵌入服務都不是必需項,不配置時對應功能(聯網搜尋、向量檢索)自動降級或不可用。SEARCH_* 支援在管理後臺配置,環境變數與後臺二選一即可,後臺配置的好處是改動不需要重啟容器,見管理後臺概覽。沙箱兩個變數留空則程式碼執行功能不可用;用官方 compose 時 sidecar 已隨套件啟動,不需要手工設定,但如果沙箱暴露在非內網環境,務必把 SANDBOX_API_KEY 從共享預設值改為隨機強金鑰(sidecar 側同步修改,見第 8 節),詳見程式碼沙箱部署。ENABLE_MOCK_PROVIDER 僅用於演示和驗證部署,生產環境保持 false。
6. OAuth 多域名
| 變數 | 預設值 | 說明 |
|---|---|---|
OAUTH_CALLBACK_BASE_URL | (空) | 多域名部署時,固定 OAuth 回撥所使用的唯一 scheme://host。 |
OAUTH_RETURN_ORIGINS | (空) | 跨域登入完成後允許跳回的 origin 白名單,逗號分隔。 |
怎麼選/常見坑:單域名部署這兩項都不需要設定。當同一套服務通過多個域名訪問,而 OAuth 提供商(如 GitHub/Google)只允許註冊固定的回撥地址時,把 OAUTH_CALLBACK_BASE_URL 設為你在提供商處註冊的那個域名;使用者從其它域名發起登入後要能跳回原域名,就把那些域名加進 OAUTH_RETURN_ORIGINS。白名單外的 origin 不會被跳轉,這是防開放重定向的安全設計,漏配會表現為「登入成功但回不到原頁面」。
7. Compose 編排層變數(.env)
以下變數寫在 compose 專案根目錄的 .env 檔案裡,由 docker-compose.yml 展開注入各容器,不是 Aivory 程序直接讀取的配置:
| 變數 | 預設值 | 說明 |
|---|---|---|
IMAGE_OWNER | hjxwz123 | 映象所有者,拼接為 ghcr.io/<IMAGE_OWNER>/aivory-app 等映象名。使用自建映象倉庫時修改。 |
IMAGE_TAG | latest | 映象標籤。生產環境建議鎖定具體版本號(如 2.2.0)而非 latest。 |
POSTGRES_USER | aivory | PostgreSQL 使用者名稱。 |
POSTGRES_PASSWORD | (必設) | PostgreSQL 密碼,無預設值,首次部署必須填寫。 |
POSTGRES_DB | aivory | PostgreSQL 資料庫名。 |
REDIS_PASSWORD | (必設) | Redis 密碼,無預設值,首次部署必須填寫。 |
QDRANT_API_KEY | aivory-internal-qdrant | Qdrant 的 API key,app 容器與 qdrant 容器共用同一個值。 |
JWT_SECRET | (必設) | 直接透傳給 app 容器,規則見第 3 節。 |
DATA_DIR | ./data | 宿主機資料目錄,掛載給各容器持久化資料。 |
怎麼選/常見坑:POSTGRES_PASSWORD、REDIS_PASSWORD、JWT_SECRET 三項沒有預設值,.env 裡漏填任何一個都會導致啟動失敗,這是有意為之的防呆設計。POSTGRES_* 修改後 compose 會用它們拼出 app 容器的 DATABASE_URL,不需要再手工寫連線串。QDRANT_API_KEY 雖有預設值,但只要 Qdrant 埠沒有暴露到 compose 網路之外就是安全的;如果你把 Qdrant 單獨對外暴露,請改為強隨機值。DATA_DIR 指向的目錄就是全部持久化狀態(資料庫、上傳、向量、備份),遷移主機時整目錄拷走即可,詳見 Docker Compose 部署。
8. 沙箱 sidecar 運維變數
以下變數作用於 aivory-sandbox-sidecar 容器(程式碼沙箱的控制面),與第 5 節 app 側的 SANDBOX_BASE_URL/SANDBOX_API_KEY 是兩端配置。sidecar 通過 Docker 為每個會話拉起隔離容器執行程式碼,整體架構見程式碼沙箱部署,使用者側功能見 Python 沙箱。
映象與容器資源
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_IMAGE | aivory-sandbox:latest | 會話容器使用的執行時映象。 |
SANDBOX_NETWORK | none | 會話容器的網路模式。預設完全斷網;設為 bridge 才允許執行時聯網(如 pip 安裝包)。 |
SANDBOX_MEMORY | 2g | 單個會話容器的記憶體上限。文件渲染類任務較吃記憶體,不建議低於預設值。 |
SANDBOX_CPUS | 1 | 單個會話容器的 CPU 配額。 |
SANDBOX_PIDS_LIMIT | 256 | 單個會話容器的程序數上限,防 fork 炸彈。 |
SANDBOX_NOFILE_ULIMIT | 1024:1024 | 會話容器的檔案描述符 ulimit(軟:硬)。 |
SANDBOX_PULL_ON_START | (空,關閉) | 非空且非 0/false 時,sidecar 啟動時先 docker pull 執行時映象一次,避免全新伺服器首個會話因映象缺失失敗。拉取是盡力而為,失敗只記日誌不阻斷啟動。 |
認證
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_API_KEY | (空) | sidecar 要求所有請求攜帶匹配的 Bearer 金鑰,校驗失敗即拒絕。金鑰為空且未顯式豁免時,sidecar 直接拒絕啟動(fail-closed)。 |
SANDBOX_ALLOW_NO_AUTH | (空,關閉) | 顯式豁免無金鑰啟動,僅限可信的 localhost 開發機。只有 1/true/yes/on 四個取值生效,其它寫法(包括 False/no/off)一律視為不豁免。 |
sidecar 直接驅動宿主機的 Docker,等價於宿主機 root 許可權。SANDBOX_ALLOW_NO_AUTH 只應出現在完全不對外的本機開發環境;生產環境必須設定強隨機的 SANDBOX_API_KEY,並與 app 側(第 5 節)保持一致。
執行超時與會話回收
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_EXEC_TIMEOUT_CAP_MS | 600000 | 單次執行超時的運維硬上限(10 分鐘)。管理後臺設定的每次呼叫超時會被鉗制到該值以內;調低即收緊天花板。 |
SANDBOX_DEFAULT_EXEC_TIMEOUT_MS | 120000 | 呼叫方未指定超時時的預設單次執行超時(120 秒),不會靜默繼承 10 分鐘硬上限。 |
SANDBOX_IDLE_TTL_SECONDS | 1800 | 會話空閒多久後被回收,預設 30 分鐘。 |
SANDBOX_IDLE_TTL_CAP_SECONDS | 86400 | 空閒回收 TTL 的運維硬上限(24 小時)。管理後臺可調短回收視窗,但永遠不能超過該上限。 |
SANDBOX_MAX_SESSIONS | 16 | 同時存活的會話容器數上限。 |
SANDBOX_MAX_CONCURRENT_EXECS | 4 | 同時執行的程式碼執行數上限。 |
SANDBOX_MAX_CONCURRENT_CREATES | 2 | 同時進行的會話建立數上限。 |
SANDBOX_QUEUE_TIMEOUT_SECONDS | 150 | 請求在併發佇列中的最長等待時間,超時報錯返回。 |
檔案系統與磁碟防護
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_READ_ONLY_ROOTFS | 1 | 會話容器根檔案系統只讀(防磁碟寫滿攻擊)。僅 /workspace、/tmp、$HOME 是有大小上限的 tmpfs。設為 0 或 false 可關閉,不建議。 |
SANDBOX_TMPFS_SIZE | 256m | /tmp 等 tmpfs 掛載的大小上限。 |
SANDBOX_WORKSPACE_SIZE | 512m | 可寫工作區 /workspace 的 tmpfs 大小上限。舊名 SANDBOX_WORKSPACE_TMPFS_SIZE 仍作為相容別名生效。 |
SANDBOX_DISK_SIZE | (空,關閉) | 會話容器可寫層的磁碟配額(如 1g)。需要 Docker overlay2 儲存驅動且啟用 pquota/prjquota,不滿足時 docker run 會報錯,因此為可選項且以盡力而為方式應用(失敗時自動去掉該引數重試)。 |
SANDBOX_SECCOMP_PROFILE | (空,關閉) | 為會話容器指定固定的 seccomp profile 檔案路徑(路徑需在 sidecar 容器內可讀)。僅在設定時附加到 docker run。 |
輸出與產物限額
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_MAX_OUTPUT_BYTES | 32768 | 單次執行 stdout/stderr 的截斷上限(32KB)。 |
SANDBOX_MAX_ARTIFACT_BYTES | 20971520 | 單個產物檔案的大小上限(20MiB)。 |
SANDBOX_MAX_TOTAL_ARTIFACT_BYTES | 52428800 | 單次執行全部產物的總大小上限(50MiB)。 |
SANDBOX_MAX_FILES_PER_EXEC | 20 | 單次執行可上傳的檔案數上限。 |
SANDBOX_MAX_UPLOAD_BYTES | 20971520 | 向沙箱上傳單個檔案的大小上限(20MiB)。 |
SANDBOX_MAX_ARCHIVE_BYTES | 209715200 | 工作區歸檔 tar 包的大小上限(200MiB)。會話 /workspace 超過該值時跳過歸檔(記日誌),會話本身仍正常回收。 |
工作區持久化
| 變數 | 預設值 | 說明 |
|---|---|---|
SANDBOX_LOCAL_STORAGE_DIR | (空,關閉) | 本地磁碟歸檔後端目錄,S3/OSS 之外的零依賴替代。設定後工作區 tar 包寫入該目錄,需掛載為卷才能跨 sidecar 重啟保留;留空時 local 後端不生效,會話被回收即工作區丟失。該路徑只能由運維通過環境變數指定,不接受遠端呼叫方傳入。 |
怎麼選/常見坑:官方 compose 已為 sidecar 填好可用預設值,多數場景只需要關心 SANDBOX_API_KEY(與 app 側一致)和是否放開 SANDBOX_NETWORK。放開網路(bridge)意味著不可信程式碼可以對外發包,請評估風險後再開。資源類上限(SANDBOX_MEMORY/SANDBOX_MAX_SESSIONS/SANDBOX_MAX_CONCURRENT_EXECS)按「宿主機記憶體 ≥ 會話數 × 單會話記憶體」估算,預設 16 會話 × 2g 的理論峰值超出小機器承受能力,小記憶體機器應先調低 SANDBOX_MAX_SESSIONS。sidecar 內部的讀迴圈節奏、S3/OSS 超時重試、請求體大小等微調項(SANDBOX_S3_*、SANDBOX_MAX_BODY_BYTES 等)歸入高階調優環境變數。
9. 前端構建期變數
| 變數 | 預設值 | 說明 |
|---|---|---|
VITE_API_BASE | /api | 前端呼叫 API 的基礎路徑,在構建時注入。僅前後端分離部署(前端靜態託管在別處)時改為 API 服務的完整地址。 |
怎麼選/常見坑:這是構建期變數,不是執行時變數:改了它必須重新構建前端產物,對已構建好的官方映象設定它沒有任何效果。單容器同源部署(預設形態)保持 /api 即可;只有把前端部署到獨立域名/CDN 時才改成 https://api.example.com/api 這類完整地址,同時記得在服務端把前端 origin 加入 ALLOWED_ORIGINS(第 3 節)。
下一步
- 首次部署從快速開始與首次執行走一遍標準流程。
- 域名與 HTTPS 接入見反向代理與 Cloudflare。
- 全部內部調優項索引見高階調優環境變數。