feat(docs): 更新 .env.template 文件和新增 Docker 启动问题模板

xerrors · xerrors · commit ed010da12160 · 2025-11-13T18:50:42.000+08:00
- 在 .env.template 文件中，重新格式化可选配置部分，确保更清晰的结构。
- 新增 Docker 启动问题的 GitHub Issue 模板，提供详细的故障排除步骤和环境信息收集指南。
- 更新 FAQ 文档，增强对 Docker 镜像拉取和服务启动失败的说明，提供更具体的解决方案和操作步骤。
- 移除 AttachmentOptionsComponent.vue 中的拖拽上传功能代码，简化组件逻辑。
diff --git 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
-
-# 功能服务
-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
-
-
-
-# region neo4j
-NEO4J_URI=
-NEO4J_USERNAME=
-NEO4J_PASSWORD=
-# endregion neo4j
-
-# Servies
-YUXI_SUPER_ADMIN_NAME=
-YUXI_SUPER_ADMIN_PASSWORD=
-
-# MinerU
-MINERU_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
+
+# # 功能服务
+# 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
+
+
+
+# # region neo4j
+# NEO4J_URI=
+# NEO4J_USERNAME=
+# NEO4J_PASSWORD=
+# # endregion neo4j
+
+# # Servies
+# YUXI_SUPER_ADMIN_NAME=
+# YUXI_SUPER_ADMIN_PASSWORD=
+
+# # MinerU
+# MINERU_API_KEY=
diff --git a/.github/ISSUE_TEMPLATE/提交一个docker启动问题.md 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
@@ -2,40 +2,67 @@
 
 以下为最常见的安装与使用问题，更多细节请参阅相应章节链接。
 
-- 首次运行如何创建管理员？
-  - Web 首次启动会引导初始化；也可调用 API：
-    - `GET /api/auth/check-first-run` → `first_run=true` 时
-    - `POST /api/auth/initialize` 提交 `user_id` 与 `password`
-  - 无默认账号，初始化后使用创建的超级管理员登录
-
-- 镜像拉取/构建失败？
-  - 可使用 `docker/pull_image.sh` 辅助拉取，或配置代理环境变量 `HTTP_PROXY/HTTPS_PROXY`
-  - 若已配置代理仍失败，可临时取消代理后重试
-  - 参考：介绍 → 快速开始 → 故障排除
-
-- 服务端口与访问地址？
-  - 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`
-
-- OCR 模型或服务不可用？
-  - RapidOCR 本地模型：确保 `MODEL_DIR/SWHL/RapidOCR` 下存在 `PP-OCRv4` 模型
-  - MinerU/PaddleX：检查健康检查接口与 GPU/CUDA 版本
-  - 参考：高级配置 → 文档解析
+## Docker与启动相关问题
+
+### 镜像拉取/构建失败？
+镜像拉取：可使用 `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
+   ```
+
+
+### 服务启动失败？
+- 检查端口占用情况：使用 `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`
+
+### 服务端口与访问地址？
+- Web: `http://localhost:5173`；API 文档: `http://localhost:5050/docs`
 
-- 支持的文件类型与常见入库失败？
-  - 查询：`GET /api/knowledge/files/supported-types`
-  - 常见失败：不支持的扩展名、内容哈希重复（去重）、OCR 服务未就绪
+### Milvus/Neo4j 启动或连接失败？
+- 重启：`docker compose up milvus -d && docker restart api-dev`
+- Neo4j 默认：用户名 `neo4j`、密码 `0123456789`、管理界面 `http://localhost:7474`
+- Milvus 检查：`docker logs milvus -f` 查看启动状态
 
-- 批量上传与转换示例？
-  - 上传入库：`uv run scripts/batch_upload.py upload --db-id <id> --directory <dir> --username <u> --password <p> --base-url http://127.0.0.1:5050/api`
-  - 参考：高级配置 → 文档解析
+### 首次运行如何创建管理员？
+- 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 版本
 
 - 登录失败被锁定？
   - 多次失败会临时锁定账户，请根据提示等待后重试
-
-- 如何查看日志和状态？
-  - `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
@@ -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();
-};
 </script>
 
 <style lang="less" scoped>
