From 267c847fb86a62c70b4e76ea8db69e8038b7d5ea Mon Sep 17 00:00:00 2001 From: wizardchen Date: Thu, 6 Aug 2026 19:27:43 +0800 Subject: [PATCH] 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. --- .env.example | 3 +-- README.md | 24 ++++++++++++----- README_CN.md | 24 ++++++++++++----- README_JA.md | 27 ++++++++++++++----- README_KO.md | 27 ++++++++++++++----- .../01-getting-started/02-installation.md | 17 +++++++++++- 6 files changed, 93 insertions(+), 29 deletions(-) diff --git a/.env.example b/.env.example index 23c419c8..c1e874d7 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index 9de07cac..83bce82a 100644 --- a/README.md +++ b/README.md @@ -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` diff --git a/README_CN.md b/README_CN.md index 97aa344f..2ef7ac0e 100644 --- a/README_CN.md +++ b/README_CN.md @@ -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` diff --git a/README_JA.md b/README_JA.md index 9a33afe6..efb0562b 100644 --- a/README_JA.md +++ b/README_JA.md @@ -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` diff --git a/README_KO.md b/README_KO.md index fc58785c..a5f30f63 100644 --- a/README_KO.md +++ b/README_KO.md @@ -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` diff --git a/website-docs/01-getting-started/02-installation.md b/website-docs/01-getting-started/02-installation.md index b2cc99eb..e6c3e54b 100644 --- a/website-docs/01-getting-started/02-installation.md +++ b/website-docs/01-getting-started/02-installation.md @@ -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 不一致。 + ### 核心服务(默认启动) | 服务 | 镜像 | 端口(宿主:容器) | 依赖 | 说明 |