mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-09-25 22:16:19 +00:00
204 lines
5.9 KiB
Plaintext
204 lines
5.9 KiB
Plaintext
---
|
||
title: 运维与排障
|
||
description: 本页面涵盖运行 DeerFlow 应用的操作信息：日志记录、常见问题和维护任务。
|
||
---
|
||
|
||
import { Callout } from "nextra/components";
|
||
|
||
# 运维与排障
|
||
|
||
本页面涵盖运行 DeerFlow 应用的操作信息：日志记录、常见问题和维护任务。
|
||
|
||
## 日志
|
||
|
||
DeerFlow 应用在 `logs/` 目录中写入每个服务的日志：
|
||
|
||
| 文件 | 内容 |
|
||
| -------------------- | -------------------------------------- |
|
||
| `logs/gateway.log` | API 请求/响应、Agent 运行时和 Gateway 错误 |
|
||
| `logs/frontend.log` | Next.js 服务器日志 |
|
||
| `logs/nginx.log` | 代理访问和错误日志 |
|
||
|
||
**实时追踪日志**：
|
||
|
||
```bash
|
||
tail -f logs/gateway.log # 查看 API 请求和 Agent 活动
|
||
```
|
||
|
||
**调整日志级别**：
|
||
|
||
```yaml
|
||
# config.yaml
|
||
log_level: debug # debug | info | warning | error
|
||
```
|
||
|
||
## 健康检查
|
||
|
||
DeerFlow 暴露健康检查端点：
|
||
|
||
```bash
|
||
# Gateway 健康状态
|
||
curl http://localhost:8001/health
|
||
|
||
# 通过 nginx 完整代理链验证
|
||
curl http://localhost:2026/api/models
|
||
```
|
||
|
||
## 升级已有的代码仓库
|
||
|
||
保留现有的 `config.yaml`、`.env` 和 `extensions_config.json`，不要再次运行
|
||
`make config`。先停止当前使用的运行模式，拉取更新，再用原模式启动：
|
||
|
||
| 当前模式 | 停止命令 | 拉取更新并重启 |
|
||
| --- | --- | --- |
|
||
| 本地开发 | `make stop` | `git pull --ff-only && make dev` |
|
||
| 本地生产 | `make stop` | `git pull --ff-only && make start` |
|
||
| Docker 开发 | `make docker-stop` | `git pull --ff-only && make docker-start` |
|
||
| Docker 生产 | `make down` | `git pull --ff-only && make up` |
|
||
|
||
不需要在每次 `git pull` 后运行 `make docker-init`，它只用于首次准备 sandbox 镜像。
|
||
如果新版本需要新增配置字段，请在重启前运行 `make config-upgrade`；该命令会保留已有值，
|
||
并在修改前生成 `config.yaml.bak`。
|
||
|
||
## 常见问题
|
||
|
||
### 模型配置错误
|
||
|
||
**症状**：Agent 在响应第一条消息时报错，日志中有 API 认证错误。
|
||
|
||
**诊断**：
|
||
|
||
```bash
|
||
# 检查 Gateway 日志中的模型错误
|
||
grep -i "error\|apikey\|unauthorized" logs/gateway.log | tail -20
|
||
```
|
||
|
||
**解决**：
|
||
|
||
1. 验证 `config.yaml` 中 API key 字段名称正确（例如 `$OPENAI_API_KEY`）。
|
||
2. 确认对应的环境变量已设置（`echo $OPENAI_API_KEY`）。
|
||
3. 检查 `base_url`（如有）是否与提供商的实际端点匹配。
|
||
|
||
---
|
||
|
||
### 沙箱权限问题
|
||
|
||
**症状**：工具报"文件未找到"或权限错误，即使 Agent 声称已创建文件。
|
||
|
||
**诊断**：
|
||
|
||
```bash
|
||
# 检查线程用户数据目录是否存在且可写
|
||
ls -la backend/.deer-flow/threads/
|
||
```
|
||
|
||
**解决**：
|
||
|
||
1. 确保 `backend/.deer-flow/` 对运行 DeerFlow 的进程可写。
|
||
2. 在 Docker 部署中，验证卷挂载路径正确（`DEER_FLOW_ROOT` 设置为绝对路径）。
|
||
3. 如果使用基于容器的沙箱，确认 Docker 已运行并且容器镜像已拉取。
|
||
|
||
---
|
||
|
||
### SQLite 报 `database is locked`
|
||
|
||
**症状**：Docker 或团队部署中，多个用户同时使用时出现 `sqlite3.OperationalError: database is locked`。
|
||
|
||
**原因**：SQLite 支持并发读取，但同一时间只有一个写入者。DeerFlow 的检查点写入和应用写入会共享同一个 SQLite 数据库文件，多用户并发时可能竞争文件锁。
|
||
|
||
**解决**：生产环境或多用户部署切换到 Postgres：
|
||
|
||
```yaml
|
||
database:
|
||
backend: postgres
|
||
postgres_url: $DATABASE_URL
|
||
|
||
run_events:
|
||
backend: db
|
||
```
|
||
|
||
SQLite 应只用于本地开发、单用户部署或短期评估环境。
|
||
|
||
---
|
||
|
||
### 前端构建失败
|
||
|
||
**症状**：`make install` 或前端构建步骤失败，提示 `BETTER_AUTH_SECRET` 错误。
|
||
|
||
**解决**：
|
||
|
||
```bash
|
||
# 选项 1：设置环境变量（推荐）
|
||
export BETTER_AUTH_SECRET=your-secret-here-at-least-32-chars
|
||
cd frontend && pnpm build
|
||
|
||
# 选项 2：跳过构建时验证（仅限开发）
|
||
SKIP_ENV_VALIDATION=1 pnpm build
|
||
```
|
||
|
||
---
|
||
|
||
### MCP 服务器连接失败
|
||
|
||
**症状**：MCP 工具未出现，`logs/gateway.log` 中有超时错误。
|
||
|
||
**诊断**：
|
||
|
||
```bash
|
||
# 检查 MCP 相关错误
|
||
grep -i "mcp\|timeout" logs/gateway.log | tail -20
|
||
```
|
||
|
||
**解决**：
|
||
|
||
1. 验证 `extensions_config.json` 中 MCP 服务器的 `command` 和 `args` 在服务器外部正常工作（手动运行命令）。
|
||
2. 确认 MCP 服务器的依赖（如 `npx`、`uvx`）已安装并在 PATH 中。
|
||
3. 检查 MCP 服务器是否需要网络访问或特定环境变量。
|
||
|
||
---
|
||
|
||
### K8s Provisioner 连接失败
|
||
|
||
**症状**：沙箱工具请求挂起，日志中有连接拒绝错误。
|
||
|
||
**解决**：
|
||
|
||
1. 验证 `config.yaml` 中 `provisioner_url` 正确且 Provisioner Pod 运行正常。
|
||
2. 检查 `K8S_NAMESPACE` 和 RBAC 配置是否允许 Provisioner 创建 Pod。
|
||
3. 验证 `SANDBOX_IMAGE` 可以从 K8s 节点拉取。
|
||
|
||
## 数据备份
|
||
|
||
根据你启用的存储后端备份：
|
||
|
||
- `backend/.deer-flow/threads/`：线程工作目录、上传文件和产出物。
|
||
- `backend/.deer-flow/memory.json` 和 `backend/.deer-flow/agents/`：全局和 Agent 记忆。
|
||
- `${database.sqlite_dir}/deerflow.db`：当使用 `database.backend: sqlite` 时备份，默认路径为 `.deer-flow/data/deerflow.db`。
|
||
- Postgres 数据库备份：当使用 `database.backend: postgres` 时定期导出。
|
||
- 旧的 `checkpointer.connection_string` 文件：如果你的部署仍配置独立 `checkpointer`。
|
||
- `backend/agents/*/config.yaml`：自定义 Agent 配置。
|
||
|
||
Docker 部署中，备份绑定挂载的宿主机路径，而不是容器内部文件系统。
|
||
|
||
## 停止和重启服务
|
||
|
||
```bash
|
||
# 停止所有本地服务
|
||
make stop
|
||
|
||
# 重启（停止后重新启动）
|
||
make stop && make dev
|
||
```
|
||
|
||
在 Docker 中：
|
||
|
||
```bash
|
||
docker compose -f docker/docker-compose-dev.yaml down
|
||
docker compose -f docker/docker-compose-dev.yaml up
|
||
```
|
||
|
||
<Cards num={2}>
|
||
<Cards.Card title="部署指南" href="/docs/application/deployment-guide" />
|
||
<Cards.Card title="配置" href="/docs/application/configuration" />
|
||
</Cards>
|