#快速开始指南

本项目是一个智能知识库和知识图谱 Agent 开发平台。 本指南将帮助你在几分钟内启动并运行系统，使你能够利用 LangGraph、RAG 技术和知识图谱构建 AI 驱动的知识应用。

#环境要求

项目采用微服务架构设计，默认服务无需 GPU 支持。如果需要使用 OCR 功能，可以通过环境变量配置外部服务。

#快速安装

#步骤一：获取项目代码

# 克隆默认分支
git clone --depth 1 https://github.com/Zhongye1/KnowAgenticRAG.git
cd KnowAgenticRAG

--depth 1 标志会创建一个浅克隆，仅包含最新的提交，从而显著减少下载时间和磁盘使用量。本仓库目前只有默认分支 master，克隆时不需要指定分支；当前版本号写在 backend/pyproject.toml 与 web/package.json 里。

#步骤二：配置环境变量

方式一：使用初始化脚本（推荐）

我们提供了自动化脚本，帮你完成环境配置和 Docker 镜像拉取：

# Linux/macOS
./scripts/init.sh

# Windows PowerShell
.\scripts\init.ps1

脚本会引导你完成以下配置：

• 创建 .env 配置文件
• 设置 SILICONFLOW_API_KEY（必需，用于调用大模型）
• 独立生成并持久保存 JWT_SECRET_KEY、API_KEY_DERIVATION_SECRET 和 SANDBOX_PROVISIONER_TOKEN
• 拒绝短于 32 字符或彼此复用的安全密钥，并将 Linux/macOS .env 权限收紧为 600
• 设置 TAVILY_API_KEY（可选，用于搜索服务）
• 自动拉取必需的 Docker 镜像

方式二：手动配置

如果偏好手动配置：

# 复制环境变量模板
cp .env.template .env

# 编辑 .env 文件，填入模型 API Key，并为下列三项分别生成不同的随机值
# JWT_SECRET_KEY=$(openssl rand -hex 32)
# API_KEY_DERIVATION_SECRET=$(openssl rand -hex 32)
# SANDBOX_PROVISIONER_TOKEN=$(openssl rand -hex 32)

也可以在复制模板后运行初始化脚本；脚本会检测已有 .env，只补齐缺失的 required 配置。三个安全密钥不能复用，后续重建与升级必须保留原值。

#步骤三：启动服务

# 构建并启动所有服务
docker compose up --build -d

从旧文件布局升级到 v0.7.2 时不能直接 up；请严格执行 生产部署与升级 中唯一维护的停机迁移流程。

服务首次启动需要等待镜像拉取和编译，请耐心等待 2-3 分钟。

task up-lite  # macOS or Linux

#步骤四：访问系统

服务启动后，访问以下地址：

首次访问时，系统会要求你设置超级管理员账号和密码，请妥善保存。

#故障排除

#查看服务状态

# 查看所有容器状态
docker ps

# 实时查看后端日志
docker logs api-dev -f

# 实时查看前端日志
docker logs web-dev -f

#部署故障排查

# 手动拉取基础镜像
bash scripts/pull_image.sh python:3.13-slim

# 在有网络的环境导出镜像，注意检查镜像列表，不一定是最新的。
bash docker/save_docker_images.sh

# 传输到目标机器
scp docker_images_xxx.tar user@host:/path/

# 导入镜像
docker load -i docker_images_xxx.tar

# Linux/macOS
export HTTP_PROXY=http://IP:PORT
export HTTPS_PROXY=http://IP:PORT

# Windows PowerShell
$env:HTTP_PROXY="http://IP:PORT"
$env:HTTPS_PROXY="http://IP:PORT"

# 重启 Milvus 服务
docker compose up milvus -d
docker restart api-dev

#下一步

• 了解如何配置模型：阅读 模型配置
• 探索知识库功能：阅读 知识库与知识图谱
• 学习智能体开发：阅读 智能体开发
• 深入了解配置系统：阅读 配置系统详解
• 理解运行时状态与边界：按顺序阅读 机制详解