docs: complete docker compose pull guidance across deployment docs

Follow up on #2567 by documenting the upgrade workflow, syncing JA/KO
READMEs and installation guide, and clarifying that WEKNORA_VERSION
changes require docker compose pull to avoid stale cached images.
main
wizardchen 2026-08-06 19:27:43 +08:00 committed by lyingbug
parent f266ac4dcf
commit 267c847fb8
6 changed files with 93 additions and 29 deletions

View File

@ -30,8 +30,7 @@
# #####################################################################
# ========== A1. 镜像版本与构建 ==========
# WeKnora 镜像版本标签:latest(稳定版)/ main(最新开发版)。
# 镜像版本标签,不指定时默认 latest。升级到指定版本(如 0.7.0)可避免本地缓存旧镜像导致版本不一致
# WeKnora 镜像版本标签:latest(稳定版)/ main(最新开发版)。升级时请将版本改为目标 release(如 0.7.0),并执行 docker compose pull 拉取对应镜像。
WEKNORA_VERSION=latest
# Alpine apk 镜像源(构建 app 镜像用,留空用默认源;国内可设 mirrors.tencent.com 加速)。
APK_MIRROR_ARG=mirrors.tencent.com

View File

@ -217,19 +217,31 @@ Once started, visit **http://localhost** to get started.
> To use a local Ollama model, run `ollama serve > /dev/null 2>&1 &` first.
### 🔄 Upgrading
If you already have WeKnora running and downloaded a newer release:
```bash
# Set WEKNORA_VERSION in .env to the target release (e.g. 0.7.0), or keep latest
docker compose pull # Pull images matching WEKNORA_VERSION
docker compose up -d # Recreate containers with new images
```
> `docker compose up -d` alone reuses locally cached images and may leave the UI version out of sync with the release you downloaded.
### 🔧 Optional Services (Docker Compose Profiles)
Add `--profile` flags to enable additional components. Multiple profiles can be combined:
| Profile | Description | Command |
|---------|-------------|---------|
| _(default)_ | Core services | `docker compose up -d` |
| `full` | All features | `docker compose --profile full up -d` |
| `neo4j` | Knowledge Graph (Neo4j) | `docker compose --profile neo4j up -d` |
| `minio` | Object Storage (MinIO) | `docker compose --profile minio up -d` |
| `langfuse` | Tracing (Langfuse) | `docker compose --profile langfuse up -d` |
| _(default)_ | Core services | `docker compose pull && docker compose up -d` |
| `full` | All features | `docker compose --profile full pull && docker compose --profile full up -d` |
| `neo4j` | Knowledge Graph (Neo4j) | `docker compose --profile neo4j pull && docker compose --profile neo4j up -d` |
| `minio` | Object Storage (MinIO) | `docker compose --profile minio pull && docker compose --profile minio up -d` |
| `langfuse` | Tracing (Langfuse) | `docker compose --profile langfuse pull && docker compose --profile langfuse up -d` |
Combine profiles: `docker compose --profile neo4j --profile minio up -d`
Combine profiles: `docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d`
Stop services: `docker compose down`

View File

@ -194,19 +194,31 @@ docker compose up -d # 启动核心服务
> 如需使用本地 Ollama 模型,请先运行 `ollama serve > /dev/null 2>&1 &`
### 🔄 版本升级
若已有部署并下载了更新的 release:
```bash
# 在 .env 中将 WEKNORA_VERSION 设为目标版本(如 0.7.0),或保持 latest
docker compose pull # 拉取与 WEKNORA_VERSION 匹配的镜像
docker compose up -d # 用新镜像重建容器
```
> 仅执行 `docker compose up -d` 会复用本地缓存镜像,可能导致 Web UI 显示版本与下载的 release 不一致。
### 🔧 可选服务(Docker Compose Profile)
按需添加 `--profile` 启动额外组件,多个 profile 可叠加使用:
| Profile | 说明 | 启动命令 |
|---------|------|----------|
| _(默认)_ | 核心服务 | `docker compose up -d` |
| `full` | 全部功能 | `docker compose --profile full up -d` |
| `neo4j` | 知识图谱 (Neo4j) | `docker compose --profile neo4j up -d` |
| `minio` | 对象存储 (MinIO) | `docker compose --profile minio up -d` |
| `langfuse` | 链路追踪 (Langfuse) | `docker compose --profile langfuse up -d` |
| _(默认)_ | 核心服务 | `docker compose pull && docker compose up -d` |
| `full` | 全部功能 | `docker compose --profile full pull && docker compose --profile full up -d` |
| `neo4j` | 知识图谱 (Neo4j) | `docker compose --profile neo4j pull && docker compose --profile neo4j up -d` |
| `minio` | 对象存储 (MinIO) | `docker compose --profile minio pull && docker compose --profile minio up -d` |
| `langfuse` | 链路追踪 (Langfuse) | `docker compose --profile langfuse pull && docker compose --profile langfuse up -d` |
组合示例:`docker compose --profile neo4j --profile minio up -d`
组合示例:`docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d`
停止服务:`docker compose down`

View File

@ -179,26 +179,39 @@ Feishu、Notion、Yuqueなどの外部プラットフォームからのナレッ
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env # 必要に応じて .env を編集(詳細はファイル内のコメント参照)
docker compose up -d # コアサービスを起動
docker compose pull # 最新イメージを取得
docker compose up -d # コアサービスを起動
```
起動後、**http://localhost** にアクセスして利用開始。
> ローカル Ollama モデルを使用する場合は、先に `ollama serve > /dev/null 2>&1 &` を実行してください。
### 🔄 アップグレード
既存のデプロイがあり、新しい release をダウンロードした場合:
```bash
# .env の WEKNORA_VERSION を対象バージョン(例: 0.7.0)に設定、または latest のまま
docker compose pull # WEKNORA_VERSION に一致するイメージを取得
docker compose up -d # 新しいイメージでコンテナを再作成
```
> `docker compose up -d` のみではローカルキャッシュのイメージが再利用され、Web UI の表示バージョンがダウンロードした release と一致しない場合があります。
### 🔧 オプションサービス(Docker Compose Profile)
`--profile` フラグで追加コンポーネントを有効化。複数の profile を組み合わせ可能:
| Profile | 説明 | コマンド |
|---------|------|---------|
| _(デフォルト)_ | コアサービス | `docker compose up -d` |
| `full` | 全機能 | `docker compose --profile full up -d` |
| `neo4j` | ナレッジグラフ (Neo4j) | `docker compose --profile neo4j up -d` |
| `minio` | オブジェクトストレージ (MinIO) | `docker compose --profile minio up -d` |
| `langfuse` | トレーシング (Langfuse) | `docker compose --profile langfuse up -d` |
| _(デフォルト)_ | コアサービス | `docker compose pull && docker compose up -d` |
| `full` | 全機能 | `docker compose --profile full pull && docker compose --profile full up -d` |
| `neo4j` | ナレッジグラフ (Neo4j) | `docker compose --profile neo4j pull && docker compose --profile neo4j up -d` |
| `minio` | オブジェクトストレージ (MinIO) | `docker compose --profile minio pull && docker compose --profile minio up -d` |
| `langfuse` | トレーシング (Langfuse) | `docker compose --profile langfuse pull && docker compose --profile langfuse up -d` |
組み合わせ例:`docker compose --profile neo4j --profile minio up -d`
組み合わせ例:`docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d`
サービス停止:`docker compose down`

View File

@ -189,26 +189,39 @@ Feishu, Notion, Yuque 등 외부 플랫폼에서 지식 자동 동기화를 지
git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env # 필요에 따라 .env 편집 (파일 내 주석 참고)
docker compose up -d # 코어 서비스 시작
docker compose pull # 최신 이미지 가져오기
docker compose up -d # 코어 서비스 시작
```
시작 후 **http://localhost** 에 접속하여 바로 사용 가능합니다.
> 로컬 Ollama 모델을 사용하려면 먼저 `ollama serve > /dev/null 2>&1 &` 를 실행하세요.
### 🔄 업그레이드
기존 배포가 있고 새 release를 다운로드한 경우:
```bash
# .env에서 WEKNORA_VERSION을 대상 버전(예: 0.7.0)으로 설정하거나 latest 유지
docker compose pull # WEKNORA_VERSION에 맞는 이미지 가져오기
docker compose up -d # 새 이미지로 컨테이너 재생성
```
> `docker compose up -d`만 실행하면 로컬 캐시 이미지가 재사용되어 Web UI 버전이 다운로드한 release와 일치하지 않을 수 있습니다.
### 🔧 선택 서비스 (Docker Compose Profile)
`--profile` 플래그로 추가 컴포넌트를 활성화합니다. 여러 profile 조합 가능:
| Profile | 설명 | 명령어 |
|---------|------|--------|
| _(기본)_ | 코어 서비스 | `docker compose up -d` |
| `full` | 전체 기능 | `docker compose --profile full up -d` |
| `neo4j` | 지식 그래프 (Neo4j) | `docker compose --profile neo4j up -d` |
| `minio` | 오브젝트 스토리지 (MinIO) | `docker compose --profile minio up -d` |
| `langfuse` | 트레이싱 (Langfuse) | `docker compose --profile langfuse up -d` |
| _(기본)_ | 코어 서비스 | `docker compose pull && docker compose up -d` |
| `full` | 전체 기능 | `docker compose --profile full pull && docker compose --profile full up -d` |
| `neo4j` | 지식 그래프 (Neo4j) | `docker compose --profile neo4j pull && docker compose --profile neo4j up -d` |
| `minio` | 오브젝트 스토리지 (MinIO) | `docker compose --profile minio pull && docker compose --profile minio up -d` |
| `langfuse` | 트레이싱 (Langfuse) | `docker compose --profile langfuse pull && docker compose --profile langfuse up -d` |
조합 예시: `docker compose --profile neo4j --profile minio up -d`
조합 예시: `docker compose --profile neo4j --profile minio pull && docker compose --profile neo4j --profile minio up -d`
서비스 중지: `docker compose down`

View File

@ -51,7 +51,10 @@ flowchart TB
```bash
git clone https://github.com/Tencent/WeKnora.git && cd WeKnora
cp .env.example .env # 编辑必填项:DB_USER/DB_PASSWORD/DB_NAME、REDIS_PASSWORD、JWT_SECRET、SYSTEM_AES_KEY
docker compose up -d --pull always
make start-all # 等价 ./scripts/start_all.sh(默认拉取最新镜像)
# 或直接:
docker compose pull # 拉取与 WEKNORA_VERSION 匹配的镜像
docker compose up -d
docker compose ps # 等所有服务变成 healthy/running
```
@ -61,6 +64,18 @@ docker compose ps # 等所有服务变成 healthy/running
> 注意:`docker-compose.yml` 的 app 服务使用 `env_file: [.env]`,`.env` 不存在会导致 compose 解析失败。`make docker-run` / `start_all.sh` 会自动 `cp .env.example .env` 或 `touch .env` 兜底。
### 版本升级
若已有部署并下载了更新的 release:
```bash
# 在 .env 中将 WEKNORA_VERSION 设为目标版本(如 0.7.0),或保持 latest
docker compose pull
docker compose up -d
```
> 仅执行 `docker compose up -d` 会复用本地缓存镜像,可能导致 Web UI 显示版本与下载的 release 不一致。
### 核心服务(默认启动)
| 服务 | 镜像 | 端口(宿主:容器) | 依赖 | 说明 |