X-Financial/docker/README.md

# Docker Compose

X-Financial 现在按运行依赖分成两层 Docker Compose：

- `docker-compose.yml`：只启动主应用容器，适合已经有远端 PostgreSQL、ONLYOFFICE 或 Qdrant 的环境。
- `docker-compose.full.yml`：启动完整本地开发栈，适合没有外部依赖、希望本机一次性跑齐所有服务的环境。

主应用容器仍然同时启动 Web 前端和 FastAPI 后端，并复用根目录 `start.sh`。
项目根目录会挂载到容器内 `/app`。

## 轻量启动：只跑主应用

适合你已经有数据库和 ONLYOFFICE 的情况。

```bash
cp .env.example .env
docker compose up -d
```

默认只会启动：

```text
main
```

打开：

```text
http://<your-linux-host>:5273
```

这条路径不会主动拉起本地 PostgreSQL、Qdrant 或 ONLYOFFICE。
数据库、ONLYOFFICE 和 Qdrant 地址都从 `.env` 或外部环境变量读取。

常见外部依赖变量：

```text
DATABASE_URL
POSTGRES_HOST
POSTGRES_PORT
ONLYOFFICE_ENABLED
ONLYOFFICE_PUBLIC_URL
ONLYOFFICE_BACKEND_URL
QDRANT_URL
```

## 完整启动：本地全栈

适合没有远端数据库和 ONLYOFFICE 的情况。

```bash
docker compose -f docker-compose.full.yml up -d
```

会启动：

```text
main
postgres
qdrant
onlyoffice
```

本地服务端口：

```text
Web:        5273
FastAPI:    8000
PostgreSQL: 55432 -> 5432
Qdrant:     6333 / 6334
ONLYOFFICE: 8082
SSH:        2223
```

完整栈会把主容器内的数据库地址指向 `postgres:5432`，
并把 Qdrant 地址指向 `http://qdrant:6333`。

ONLYOFFICE 默认使用本机可访问地址：

```text
http://127.0.0.1:8082
```

如果浏览器从另一台机器访问，需要覆盖：

```bash
LOCAL_ONLYOFFICE_PUBLIC_URL=http://<host>:8082 \
docker compose -f docker-compose.full.yml up -d
```

如果 ONLYOFFICE 回调后端也需要外部地址，可以同时覆盖：

```bash
LOCAL_ONLYOFFICE_BACKEND_URL=http://<host>:8000 \
docker compose -f docker-compose.full.yml up -d
```

## 可选：只额外启动本地 PostgreSQL

如果只想在轻量主容器旁边补一个本地 PostgreSQL，可以使用覆盖文件：

```bash
docker compose -f docker-compose.yml -f docker-compose.postgres.yml up -d
```

这会启动：

```text
main
postgres
```

## 停止与清理

停止当前默认轻量栈：

```bash
docker compose down
```

停止完整本地栈：

```bash
docker compose -f docker-compose.full.yml down
```

如需删除本地数据卷，先确认不再需要其中数据，再手动执行带 `-v` 的清理命令。