Common Questions

This page summarizes the most frequently asked questions about deployment operations and daily use. At the end of each answer there is a link to the corresponding manual page, for details please go to the corresponding page.

Installation and First Operation

Where did the first administrator account come from?

Aivory does not pre-set administrator credentials through environmental variables. When new deployments (user number 0) are deployed, access to the site automatically goes to the first-run setup page. /setup Fill in a mailbox, name and password (at least 8 characters), which immediately becomes an administrator and automatically logs in without mailbox verification.

If there is an account in the case, /setup 就** Permanently invalid ** Return to 409 if you open it. /setup If you see an error message stating that the instance has been initialized, go to the normal login process.

Detailed Operation for the first time。

Why doesn’t the model appear in the selector?

Check in the following order:

1. ** Channel not installed. ** Add upstream to the admin console (type: Anthropic / OpenAI / Gemini / OpenAI compatible, fill out Base URL + API Key).
2. ** model not created or not enabled **: Then go to the model page to create a model (choose channel, fill in the upstream model ID) and confirm that ** Activated ** Only the enabled model appears in all user selectors.
3. ** Selection of labels ** At the top of the model picker there is a label filter chip, which confirms that there is currently no label selected to filter the target model, and then cuts back to "all".

If you just want to experience the interface first, you can set it in Compose. ENABLE_MOCK_PROVIDER=true Enable the built-in demo model (default false)。

Detailed Channel and Model。

JWT_SECRET must be set up and why should everyone log in again after reboot?

Divided into two situations:

• ** The development environment **: JWT_SECRET Automatically generates a random temporary API key when not set. ** Each time the process is restarted, all sessions are invalid. ** Everyone needs to re-log in. If you also want to resume sessions across the development environment, set a fixed value.
• ** Deployment of Environment ** (AIVORY_ENV not dev, or DATABASE_URL Pointing to Postgres): must be set up ** At least 32 characters. **的 JWT_SECRET Otherwise, the service will refuse to start.

The token is valid from ACCESS_TTL By admission 30m) and REFRESH_TTL By admission 720h 30 days) control, go duration format.

Detailed The Core Configuration。

Functional use

Why is the knowledge base search result empty?

The two most common reasons:

1. ** Uncontained back end. **: QDRANT_URL The default is empty, the space-time vector retrieval is disabled, and the full RAG injection returns. Small documentation is still available, but the actual vector retrieval requires configuration of Qdrant (producing Compose is built-in).
2. ** Unconfigured embedding model ** Knowledge base documentation requires an embedding model. EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL By admission text-embedding-3-small Configure an embedding model in the admin console.

Confirm that the file has arrived. ready (State stream: pending → parsing → embedding → ready), the document in the middle state is not involved in retrieving.

Detailed The knowledge base与The Core Configuration。

EMBEDDING_DIM does not match the embedding model.

EMBEDDING_DIM admittedly 1536 corresponding to text-embedding-3-small Qdrant collection is named by dimension aivory_c<维度> If you exchange the embedding model for the output dimension, you must EMBEDDING_DIM Change the actual dimension of the new model, otherwise the vector writing and retrieving will fall on the wrong collection.

After changing the dimension, go to the admin console “Backup & Migration”. ** Vector maintenance ** Rebuilding vector: The system re-calls the embedding model from the fragmented text stored in the database to a new collection, not requiring the original file, but consuming embedded API calls.

Detailed Backup and Migration。

Can the scanning version of the PDF upload not resolve the content?

PDFs with text layers have local millisecond resolution and do not rely on any external services; but ** Scanning of PDF ** (and DOCX / PPTX / XLSX / image) need to go MinerU cloud OCR. Please confirm that it is configured:

varied	The default value	Explained
MINERU_API_URL	Empty (composite by default https://mineru.net)	MinerU API address
MINERU_API_KEY	空	MinerU's API key, unconfigured scan cannot be resolved

Detailed The knowledge base。

Can the code in the sandbox be connected?

admittedly ** cannot ** Sandbox Network by Compose Variable SANDBOX_NETWORK Control, the default value is none (Absolutely networkless), this is the deliberate security default value. Only change it to when the sandbox code actually needs access to the Internet bridge。

Without the network, most scenarios can be covered: the model is in the sandbox. 外用 web_fetch / fetch_image The tool scraps web pages and images, and the captured content is automatically stored in the sandbox. /workspace/uploads/ Python code can be read directly.

Without a sandbox.

SANDBOX_BASE_URL for the time, python_execute Enter safe mode and only perform simple algorithms. Production Compose has built-in sandbox containers (SANDBOX_BASE_URL=http://sandbox:8000)。

Detailed The Sandbox Deployment与 Use of Python Sandbox。

Where to change the size limit?

Three levels:

1. ** Hard service limits **: MAX_UPLOAD_BYTES and admitted 52428800 (50 MB), no upload can exceed it.
2. ** Admin Console restrictions ** The administrator can press the back. ** Pictured 和 Documentary ** Separately tighten the limit (can only be smaller than the hard upper limit).
3. ** The reverse proxy ** If you go to Nginx and other countergenerations, you also need to enlarge the upper limit of the request body of the agent layer (such as client_max_body_size Otherwise, the request will be rejected before arriving at Aivory.

Backup imports are another independent upper limit: MAX_BACKUP_BYTES The default is 20 GiB.

Detailed The Core Configuration、Place set up.与The reverse proxy。

How many messages can each user send and how many images can they generate per day?

Global default values at the environmental variable level:

varied	The default value	Explained
DAILY_MESSAGE_LIMIT	200	Number of messages per user per day
IMAGE_DAILY_LIMIT	30	Number of images generated per user per day

Additionally, administrators can make more detailed controls through user groups, credits and model quota (time limits, permanent credits, pre-send fee checks, redeem code). Users and quota。

Deployment and Networking

Is it possible to deploy HTTP?

Aivory front end has been characterized by the browser’s encryption capabilities: in a non-secure context (HTTP express), requests for signatures and other functions automatically return to pure JS implementation, not relying on HTTPS only. crypto.subtle Waiting for fire.

Recommended for HTTPS.

Text transmission means that passwords, tokens, and conversation content can be intercepted on the network; in addition, some browser capabilities (such as PWA installation) are only available in a secure context.

Detailed The reverse proxy与 Cloudflare access。

How to change domain name?

Single container deployment under the same source, Aivory ** Adapting to Domain Names ** The front and /api The same source, analyze which domain name can be used, no need to change ALLOWED_ORIGINS Or any origin configuration.Change the domain name only:

1. Add DNS to the server and update the reverse proxy. server_name with the certificate.
2. If OAuth login is configured: Multi-domain name or domain name change scenario must be set OAUTH_CALLBACK_BASE_URL fixed recovery. scheme://host synchronize and update the OAuth provider-side referral address; cross-domain logins also need to add the origin that allows referrals OAUTH_RETURN_ORIGINS The White List.
3. only is ** Separation in front. ** Deployment needs maintenance. ALLOWED_ORIGINS Attention and attention to the front end. VITE_API_BASE It is a construction variable and changes need to be rebuilt.

Detailed The Core Configuration与The reverse proxy。

Is it SQLite or Postgres?

DATABASE_URL By default pointing to the embedded SQLite (./data/aivory.db (WAL mode), zero dependency can be launched, suitable for personal use and small-scale trials; postgres:// The prefix is switched to PostgreSQL, and Compose is produced by default using Postgres 16.

Attention to: DATABASE_URL A reference to Postgres will be viewed as a “deployment environment” that triggers security checks at the deployment level (such as mandatory requirements). JWT_SECRET At least 32 characters.

No need to worry about the selection: Thanks to the engine-neutral backup format, SQLite can import full backups to Postgres deployments at any time after starting without losing any data. The SQLite model。

Data and upgrades

Forgot my administrator password?

From high to low by availability:

1. ** Return the code. ** Go to the login page "Forgot Password" and reset the 6-bit authentication code sent to the mailbox (the authentication code will be canceled 5 times in a row, it will need to be restarted).
2. ** Another administrator helps. ** If there are other administrator accounts in the instance, your password can be modified by the other party in the user management of the admin console.
3. ** Recovery from backup. ** If none of the above is possible and you have a full backup, you can log in with the account password in the backup after importing the backup.

attention to /setup It is permanently invalid on instances of existing accounts and cannot be used to rebuild administrators. Account management与Users and quota。

Can backups be restored across the database engine?

This is the core design of the Aivory backup format. Complete backup is a single zip:manifest + one JSONL (engine neutral) per table + optional file directory + optional Qdrant vector point. SQLite backup can be imported into Postgres deployments, and vice versa, sequences and external keys are processed automatically.

Attention should be paid to the importation:

• Introduction is ** Replacing the whole box. ** Requires a confirmation word. REPLACE All current sessions are terminated after completion, re-log in with the account password in the backup.
• Security Mechanism: In addition to "execute the imported administrator mailbox", the other administrators brought backup are all downgraded to ordinary users (prevent malicious backup withdrawal). ** The first instance administrator's mailbox should be the same as the old instance administrator. **。
• Introduce the upper limit MAX_BACKUP_BYTES (The default is 20 GiB).
• If the backup does not include a vector, it is possible to reconstruct text from the database block in vector maintenance without the need for the original file.

Detailed Backup and Migration。

How to upgrade to a new version?

The standard process:

cd Aivory/deploy
# 建议先在管理后台导出一份完整备份
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Database structure when a new version is launched ** Automated Migration ** No need to manually execute SQL. mirror tag by .env Inside is IMAGE_TAG Controlled (Controlled latest It can also be used in specific versions).

Upgrade prior to upgrade

Although the migration is automatic, it is recommended to export a full backup from the admin console Backup & Migration before each upgrade, and the entire library can be restored if needed.

Detailed Deployment of Docker Compose与Backup and Migration。