常見問題

本頁彙總自部署運維與日常使用中最高頻的問題。每個答案末尾附有對應手冊頁連結,深入細節請前往相應頁面。

安裝與首次執行

首次登入的管理員賬號是哪來的?

Aivory 不通過環境變數預置管理員憑據。全新部署(使用者數為 0)時,訪問站點會自動進入首啟設定頁 /setup:填寫郵箱、名字和密碼(至少 8 個字元),該賬號立即成為管理員並自動登入,無需郵箱驗證。

一旦例項中存在任何賬號,/setup 就永久失效(再訪問返回 409)。所以如果你開啟 /setup 看到報錯,說明該例項已經初始化過,請走正常登入流程。

詳見首次執行。

模型為什麼不出現在選擇器裡?

按以下順序排查:

1. 渠道未配置:先到管理後臺「渠道」新增上游(型別:Anthropic / OpenAI / Gemini / OpenAI 相容,填 Base URL + API Key)。
2. 模型未建立或未啟用:再到「模型」頁面建立模型(選渠道、填上游模型 ID),並確認已啟用。只有啟用的模型才會出現在所有使用者的選擇器裡。
3. 標籤篩選:模型選擇器頂部有標籤篩選晶片,確認當前沒有選中一個把目標模型過濾掉的標籤,切回「全部」即可。

如果只是想先體驗介面,可以在 Compose 中設定 ENABLE_MOCK_PROVIDER=true 啟用內建演示模型(預設 false)。

詳見渠道與模型。

JWT_SECRET 一定要設嗎?為什麼重啟後所有人都要重新登入?

分兩種情況:

• 開發環境:JWT_SECRET 未設定時自動生成隨機臨時金鑰。副作用是每次重啟程序,全部會話失效,所有人需要重新登入。如果你在開發環境也想會話跨重啟存活,設一個固定值即可。
• 部署環境(AIVORY_ENV 非 dev,或 DATABASE_URL 指向 Postgres):必須設定至少 32 個字元的 JWT_SECRET,否則服務直接拒絕啟動。

令牌有效期由 ACCESS_TTL(預設 30m)和 REFRESH_TTL(預設 720h,即 30 天)控制,Go duration 格式。

詳見核心配置。

功能使用

為什麼知識庫檢索結果為空?

最常見的兩個原因:

1. 未配置向量後端:QDRANT_URL 預設為空,為空時向量檢索被停用,RAG 走全文注入回退。小文件仍然可用,但真正的向量檢索需要配置 Qdrant(生產 Compose 已內建)。
2. 未配置嵌入模型:知識庫文件入庫需要嵌入模型。通過 EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL(預設 text-embedding-3-small)配置,或在管理後臺設定嵌入模型。

另外確認文件狀態已到 ready(狀態流:pending → parsing → embedding → ready),卡在中間狀態的文件不參與檢索。

詳見知識庫與核心配置。

EMBEDDING_DIM 與嵌入模型不匹配怎麼辦?

EMBEDDING_DIM 預設 1536(對應 text-embedding-3-small)。Qdrant collection 按維度命名為 aivory_c<維度>,如果你換用了輸出維度不同的嵌入模型,必須把 EMBEDDING_DIM 改成新模型的真實維度,否則向量寫入與檢索會落在錯誤的 collection 上。

修改維度後,到管理後臺「備份與遷移」的向量維護裡重建向量:系統會從資料庫儲存的分塊文本重新呼叫嵌入模型寫入新 collection,不需要原始檔案,但會消耗嵌入 API 呼叫。

詳見備份與遷移。

掃描版 PDF 上傳後解析不出內容?

帶文字層的 PDF 在本地毫秒級解析,不依賴任何外部服務;但掃描件 PDF(以及 DOCX / PPTX / XLSX / 圖片)需要走 MinerU 雲端 OCR。請確認已配置:

變數	預設值	說明
MINERU_API_URL	空(Compose 裡預設 https://mineru.net)	MinerU API 地址
MINERU_API_KEY	空	MinerU 的 API 金鑰,未配置則掃描件無法解析

詳見知識庫。

沙箱裡的程式碼能聯網嗎?

預設不能。沙箱網路由 Compose 變數 SANDBOX_NETWORK 控制,預設值為 none(完全無網路),這是刻意的安全預設值。只有當沙箱內程式碼確實需要訪問網際網路時,才把它改為 bridge。

不開網路也能覆蓋大部分場景:模型會在沙箱外用 web_fetch / fetch_image 工具抓取網頁和圖片,抓到的內容自動暫存進沙箱的 /workspace/uploads/,Python 程式碼直接讀檔案即可。

未配置沙箱時

SANDBOX_BASE_URL 為空時,python_execute 進入安全模式,只執行簡單算術。生產 Compose 已內建沙箱容器(SANDBOX_BASE_URL=http://sandbox:8000)。

詳見沙箱部署與 Python 沙箱使用。

上傳大小限制在哪裡改?

分三層:

1. 服務端硬上限:MAX_UPLOAD_BYTES,預設 52428800(50 MB),任何上傳都不能超過它。
2. 管理後臺細化限制:管理員可以在後臺按圖片和檔案分別收緊限制(只能比硬上限更小)。
3. 反向代理:如果走 Nginx 等反代,還需要調大代理層的請求體上限(如 client_max_body_size),否則請求在到達 Aivory 之前就被反代拒絕。

備份匯入是另一個獨立的上限:MAX_BACKUP_BYTES,預設 20 GiB。

詳見核心配置、站點設定與反向代理。

每個使用者每天能發多少條訊息、生成多少張圖?

環境變數層面的全域性預設值:

變數	預設值	說明
DAILY_MESSAGE_LIMIT	200	每使用者每日訊息條數
IMAGE_DAILY_LIMIT	30	每使用者每日圖片生成張數

在此之上,管理員還可以通過使用者組、積分與按模型配額做更精細的控制(定時額度、永久積分、傳送前費用預檢、兌換碼)。詳見使用者與配額。

部署與網路

用 HTTP 明文部署可以嗎?

可以正常工作。Aivory 前端對瀏覽器加密能力做了特性檢測:在非安全上下文(HTTP 明文)下,請求籤名等功能自動回退到純 JS 實現,不依賴只有 HTTPS 才提供的 crypto.subtle 等 API。

仍然建議上 HTTPS

明文傳輸意味著密碼、令牌與對話內容在網路上可被竊聽;此外瀏覽器的部分能力(如 PWA 安裝)只在安全上下文下可用。生產環境建議用反向代理或 Cloudflare 終結 TLS。

詳見反向代理與 Cloudflare 接入。

如何更換域名?

單容器同源部署下,Aivory 對域名自適應:前端與 /api 同源,解析到哪個域名哪個域名就能用,不需要改 ALLOWED_ORIGINS 或任何 origin 配置。更換域名只需:

1. 把新域名的 DNS 解析指到伺服器,更新反向代理的 server_name 與證書。
2. 如果配置了 OAuth 登入:多域名或換域名場景需設定 OAUTH_CALLBACK_BASE_URL 固定回撥的 scheme://host,並同步更新 OAuth 提供商側的回撥地址;跨域登入還需把允許跳回的 origin 加入 OAUTH_RETURN_ORIGINS 白名單。
3. 只有前後端分離部署才需要維護 ALLOWED_ORIGINS(逗號分隔),並注意前端的 VITE_API_BASE 是構建期變數,改動需重新構建。

詳見核心配置與反向代理。

該選 SQLite 還是 Postgres?

DATABASE_URL 預設指向嵌入式 SQLite(./data/aivory.db,WAL 模式),零依賴即可啟動,適合個人使用與小規模試用;postgres:// 字首則切換到 PostgreSQL,生產 Compose 預設使用 Postgres 16。

注意:DATABASE_URL 指向 Postgres 會被視為「部署環境」,觸發部署級安全校驗(例如強制要求 JWT_SECRET 至少 32 字元)。

選型不必焦慮:得益於引擎中立的備份格式,SQLite 起步後隨時可以把全量備份匯入 Postgres 部署,不丟任何資料。詳見 SQLite 模式。

資料與升級

忘記管理員密碼怎麼辦?

按可用性從高到低:

1. 找回密碼流程:登入頁走「忘記密碼」,通過傳送到郵箱的 6 位驗證碼重置(驗證碼連錯 5 次會作廢,需重新發起)。
2. 另一位管理員協助:如果例項中還有其他管理員賬號,可由對方在管理後臺的使用者管理中修改你的密碼。
3. 從備份恢復:如果以上都不可行且你有完整備份,匯入備份後可以用備份中的賬號密碼登入。

注意 /setup 在已有賬號的例項上永久失效,不能靠它重建管理員。詳見賬號管理與使用者與配額。

備份能跨資料庫引擎恢復嗎?

能,這是 Aivory 備份格式的核心設計。完整備份是單個 zip:manifest + 每表一個 JSONL(引擎中立)+ 可選的檔案目錄 + 可選的 Qdrant 向量點位。SQLite 備份可以匯入 Postgres 部署,反之亦然,序列與外部索引鍵自動處理。

匯入時需注意:

• 匯入是整庫替換,需要輸入確認詞 REPLACE;完成後當前所有會話失效,用備份裡的賬號密碼重新登入。
• 安全機制:除「執行匯入的管理員郵箱」外,備份帶來的其它 admin 一律降級為普通使用者(防惡意備份提權)。因此新例項首啟管理員的郵箱應與舊例項管理員一致。
• 匯入大小上限為 MAX_BACKUP_BYTES(預設 20 GiB)。
• 若備份未含向量,可在「向量維護」裡從資料庫分塊文本重建,無需原始檔案。

詳見備份與遷移。

如何升級到新版本?

標準流程:

cd Aivory/deploy
# 建議先在管理後臺匯出一份完整備份
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

資料庫結構在新版本啟動時自動遷移,無需手工執行 SQL。映象 tag 由 .env 中的 IMAGE_TAG 控制(預設 latest;也可以釘住具體版本號)。

升級前備份

雖然遷移是自動的,仍建議每次升級前在管理後臺「備份與遷移」匯出一份完整備份,萬一需要回退可以整庫恢復。

詳見 Docker Compose 部署與備份與遷移。