From ed010da12160ffa8259d77d21f5391b2300e8e13 Mon Sep 17 00:00:00 2001 From: Wenjie Zhang Date: Thu, 13 Nov 2025 18:50:42 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=9B=B4=E6=96=B0=20.env.templat?= =?UTF-8?q?e=20=E6=96=87=E4=BB=B6=E5=92=8C=E6=96=B0=E5=A2=9E=20Docker=20?= =?UTF-8?q?=E5=90=AF=E5=8A=A8=E9=97=AE=E9=A2=98=E6=A8=A1=E6=9D=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 在 .env.template 文件中，重新格式化可选配置部分，确保更清晰的结构。 - 新增 Docker 启动问题的 GitHub Issue 模板，提供详细的故障排除步骤和环境信息收集指南。 - 更新 FAQ 文档，增强对 Docker 镜像拉取和服务启动失败的说明，提供更具体的解决方案和操作步骤。 - 移除 AttachmentOptionsComponent.vue 中的拖拽上传功能代码，简化组件逻辑。 --- .env.template | 56 ++++++------ .../ISSUE_TEMPLATE/提交一个docker启动问题.md | 87 +++++++++++++++++++ docs/latest/changelog/faq.md | 83 ++++++++++++------ .../components/AttachmentOptionsComponent.vue | 18 ---- 4 files changed, 170 insertions(+), 74 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/提交一个docker启动问题.md diff --git a/.env.template b/.env.template index 21f57570..32dadf90 100644 --- a/.env.template +++ b/.env.template @@ -5,38 +5,38 @@ SAVE_DIR=./saves # 推荐使用硅基流动免费服务 SILICONFLOW_API_KEY= -# 其余可选配置 -OPENAI_API_KEY= -OPENAI_API_BASE= -ZHIPUAI_API_KEY= -DASHSCOPE_API_KEY= -DEEPSEEK_API_KEY= -ARK_API_KEY= -TOGETHER_API_KEY= -# endregion model_provider +# # 其余可选配置 +# OPENAI_API_KEY= +# OPENAI_API_BASE= +# ZHIPUAI_API_KEY= +# DASHSCOPE_API_KEY= +# DEEPSEEK_API_KEY= +# ARK_API_KEY= +# TOGETHER_API_KEY= +# # endregion model_provider -# 功能服务 -TAVILY_API_KEY= +# # 功能服务 +# TAVILY_API_KEY= -# 基础配置示例 -MYSQL_HOST=192.168.1.100 -MYSQL_USER=username -MYSQL_PASSWORD=your_secure_password -MYSQL_DATABASE=database_name -MYSQL_PORT=3306 -MYSQL_CHARSET=utf8mb4 +# # 基础配置示例 +# MYSQL_HOST=192.168.1.100 +# MYSQL_USER=username +# MYSQL_PASSWORD=your_secure_password +# MYSQL_DATABASE=database_name +# MYSQL_PORT=3306 +# MYSQL_CHARSET=utf8mb4 -# region neo4j -NEO4J_URI= -NEO4J_USERNAME= -NEO4J_PASSWORD= -# endregion neo4j +# # region neo4j +# NEO4J_URI= +# NEO4J_USERNAME= +# NEO4J_PASSWORD= +# # endregion neo4j -# Servies -YUXI_SUPER_ADMIN_NAME= -YUXI_SUPER_ADMIN_PASSWORD= +# # Servies +# YUXI_SUPER_ADMIN_NAME= +# YUXI_SUPER_ADMIN_PASSWORD= -# MinerU -MINERU_API_KEY= \ No newline at end of file +# # MinerU +# MINERU_API_KEY= \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/提交一个docker启动问题.md b/.github/ISSUE_TEMPLATE/提交一个docker启动问题.md new file mode 100644 index 00000000..33d3b4a6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/提交一个docker启动问题.md @@ -0,0 +1,87 @@ +--- +name: 提交一个启动问题 +about: Docker镜像拉取、服务启动、端口占用等相关问题 +title: 'Startup: ' +labels: startup +assignees: '' + +--- + +## 1️⃣ 问题描述 + +请清晰描述您在使用 Docker 或启动服务时遇到的问题： +- 操作步骤：您执行了什么操作？ +- 预期结果：您期望看到什么？ +- 实际结果：实际发生了什么？ + +例如："执行 `docker compose up -d` 后，api-dev 服务一直重启，查看日志显示无法连接到 Milvus" + +您可以先看一下常见问题与解决方案：https://xerrors.github.io/Yuxi-Know/latest/changelog/faq.html + + +## 2️⃣ 环境信息 + +请提供以下信息，帮助我们快速定位问题： +- 操作系统：Windows/macOS/Linux 及版本 +- Docker 版本：执行 `docker --version` 输出 +- Docker Compose 版本：执行 `docker compose --version` 输出 +- 项目版本：执行 `git rev-parse HEAD` 输出 + + +## 3️⃣ 启动命令 + +请提供您使用的完整启动命令： +```bash +# 例如 +docker compose up -d +# 或 +make start +``` + + +## 4️⃣ 日志信息 + +请提供相关服务的日志（至少包含最近 100 行）： + +```bash +# 查看所有服务状态 +docker ps + +# 查看 api-dev 服务日志 +docker logs --tail=100 api-dev + +# 查看所有服务日志 +docker compose logs --tail=100 +``` + +将日志粘贴到下方（可根据问题相关性选择部分日志）： + +``` +# api-dev 日志 +... + +# 其他相关服务日志 +... +``` + + +## 5️⃣ 配置文件（可选） + +如果您修改过 `docker-compose.yml` 或 `.env` 文件，请提供相关配置片段（注意隐藏敏感信息）： + +```yaml +# docker-compose.yml 相关部分 +... + +# .env 相关部分 +... +``` + + +## 6️⃣ 其他信息 + +您还可以提供以下信息帮助我们解决问题： +- 是否已尝试过重启 Docker 服务？ +- 是否已清理过 Docker 缓存或旧容器？ +- 网络环境是否有特殊配置（如代理、防火墙等）？ +- 是否有其他相关的错误提示或截图？ diff --git a/docs/latest/changelog/faq.md b/docs/latest/changelog/faq.md index 5e0fad90..ec486799 100644 --- a/docs/latest/changelog/faq.md +++ b/docs/latest/changelog/faq.md @@ -2,40 +2,67 @@ 以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。 -- 首次运行如何创建管理员？ - - Web 首次启动会引导初始化；也可调用 API： - - `GET /api/auth/check-first-run` → `first_run=true` 时 - - `POST /api/auth/initialize` 提交 `user_id` 与 `password` - - 无默认账号，初始化后使用创建的超级管理员登录 +## Docker与启动相关问题 -- 镜像拉取/构建失败？ - - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY` - - 若已配置代理仍失败，可临时取消代理后重试 - - 参考：介绍 → 快速开始 → 故障排除 +### 镜像拉取/构建失败？ +镜像拉取：可使用 `docker/pull_image.sh` 辅助拉取 +构建失败：若配置了代理仍失败，可尝试以下步骤： +1. 注释 `api.Dockerfile` 中的代理环境变量设置： + ```dockerfile + # 注释掉以下代理配置 + # ENV HTTP_PROXY=$HTTP_PROXY \ + # HTTPS_PROXY=$HTTPS_PROXY \ + # http_proxy=$HTTP_PROXY \ + # https_proxy=$HTTPS_PROXY + ``` +2. 注释 `docker-compose.yml` 中的代理构建参数： + ```yaml + services: + api: + build: + context: . + dockerfile: docker/api.Dockerfile + # 注释掉代理构建参数 + # args: + # HTTP_PROXY: ${HTTP_PROXY:-} + # HTTPS_PROXY: ${HTTPS_PROXY:-} + ``` +3. 在 `api.Dockerfile` 中添加国内镜像源加速依赖安装： + ```dockerfile + RUN --mount=type=cache,target=/root/.cache/uv \ + uv sync --no-dev --index-url https://pypi.tuna.tsinghua.edu.cn/simple + ``` -- 服务端口与访问地址？ - - Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs` - - 端口一览与说明见：高级配置 → 其他配置 → 服务端口 -- Milvus/Neo4j 启动或连接失败？ - - 重启：`docker compose up milvus -d && docker restart api-dev` - - Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474` +### 服务启动失败？ +- 检查端口占用情况：使用 `lsof -i :5050` 或 `netstat -tuln | grep 5050` 查看端口使用 +- 确认 Docker 服务状态：`systemctl status docker`（Linux）或 `Docker Desktop` 应用状态（Windows/macOS） +- 参考日志定位问题：`docker logs --tail=100 api-dev`、`docker logs --tail=100 web-dev` -- OCR 模型或服务不可用？ +### 服务端口与访问地址？ +- Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs` + +### Milvus/Neo4j 启动或连接失败？ +- 重启：`docker compose up milvus -d && docker restart api-dev` +- Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474` +- Milvus 检查：`docker logs milvus -f` 查看启动状态 + +### 首次运行如何创建管理员？ +- Web 首次启动会引导初始化；也可调用 API： + - `GET /api/auth/check-first-run` → `first_run=true` 时 + - `POST /api/auth/initialize` 提交 `user_id` 与 `password` +- 无默认账号，初始化后使用创建的超级管理员登录 + +### 如何查看日志和状态？ +- `docker ps` 查看整体服务状态 +- `docker logs api-dev -f`、`docker logs web-dev -f` 查看实时服务日志 +- `docker compose logs --tail=100` 查看所有服务日志 + +## 其他常见问题 + +### OCR 模型或服务不可用？ - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型 - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本 - - 参考：高级配置 → 文档解析 - -- 支持的文件类型与常见入库失败？ - - 查询：`GET /api/knowledge/files/supported-types` - - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪 - -- 批量上传与转换示例？ - - 上传入库：`uv run scripts/batch_upload.py upload --db-id --directory --username --password

--base-url http://127.0.0.1:5050/api` - - 参考：高级配置 → 文档解析 - 登录失败被锁定？ - 多次失败会临时锁定账户，请根据提示等待后重试 - -- 如何查看日志和状态？ - - `docker ps` 查看整体；`docker logs api-dev -f`、`docker logs web-dev -f` 查看服务日志 diff --git a/web/src/components/AttachmentOptionsComponent.vue b/web/src/components/AttachmentOptionsComponent.vue index 541e157b..3706f152 100644 --- a/web/src/components/AttachmentOptionsComponent.vue +++ b/web/src/components/AttachmentOptionsComponent.vue @@ -140,24 +140,6 @@ const processImageUpload = async (file) => { } }; -// 支持拖拽上传 -const handleDrop = (event) => { - event.preventDefault(); - const files = event.dataTransfer.files; - - if (files && files.length > 0) { - for (const file of files) { - if (file.type.startsWith('image/')) { - processImageUpload(file); - break; // 一次只处理一张图片 - } - } - } -}; - -const handleDragOver = (event) => { - event.preventDefault(); -};