Files
mirror-3x-ui/docs/content/docs/zh/reference/database.mdx
T
MHSanaei 9b91f0f42e docs: vendor the documentation site into the monorepo
Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to
docs.sanaei.dev) into docs/ so the panel and its documentation share a single
source of truth, the way sing-box keeps its docs in-tree. The old repo becomes
redundant and can be retired.

- Import the full site under docs/ (app, components, content, lib, public,
  scripts, config). The self-contained pnpm project sits alongside the existing
  engineering notes with no filename collisions.
- Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's
  docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx).
- Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to
  docs/** and run with working-directory: docs, since GitHub only runs
  workflows from the repo-root .github/. deploy-static.yml's GitHub Pages
  publish (CNAME docs.sanaei.dev) carries over unchanged.

Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to
this repository's Pages (or set the Vercel project's root directory to docs),
confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
2026-07-07 23:07:14 +02:00

63 lines
1.9 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: 数据库
description: 3x-ui 的存储后端——SQLite(默认)与 PostgreSQL——涵盖数据库路径、连接池以及从 SQLite 到 PostgreSQL 的迁移。
icon: Database
---
3x-ui 将所有内容——入站、客户端、设置——都存储在数据库中。你在安装时
选择后端;两者都是一等支持。
## SQLite(默认)
位于 `/etc/x-ui/x-ui.db` 的单个文件。无需任何配置,适合中小型
部署。该文件夹可通过
[`XUI_DB_FOLDER`](/docs/reference/env-vars#database) 配置(在 Windows 上默认
紧挨着二进制文件存放)。
## PostgreSQL
推荐用于客户端数量庞大或多节点的部署。安装程序既可以为你在本地
安装 PostgreSQL,也可以接受指向现有服务器的 DSN。运行时通过环境变量
选择后端,安装程序会将这些变量写入 `/etc/default/x-ui`:
```bash title="/etc/default/x-ui"
XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
```
使用 `XUI_DB_MAX_OPEN_CONNS` 和 `XUI_DB_MAX_IDLE_CONNS` 调优连接池。
### Docker
`docker compose up -d` 仍然使用 SQLite。若要配合内置的 PostgreSQL
服务运行,请取消 `docker-compose.yml` 中两行 `XUI_DB_*` 的注释,并使用
对应的 profile 启动:
```bash
docker compose --profile postgres up -d
```
## 从 SQLite 迁移到 PostgreSQL
使用内置命令将现有的 SQLite 安装迁移到 PostgreSQL:
```bash
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
```
然后在 `/etc/default/x-ui` 中设置 `XUI_DB_TYPE` 和 `XUI_DB_DSN` 并重启:
```bash
systemctl restart x-ui
```
<Callout type="info">
源 SQLite 文件不会被改动——只有在你确认新后端正常工作后,才手动
将其删除。
</Callout>
## 备份
无论使用哪种后端,都要定期备份——参见
[备份与恢复](/docs/operations/backup-restore)。