DeepPath Knowledge 安装使用说明书
本说明书面向普通用户，无需任何编程知识。按照步骤操作，大约 15–30 分钟即可完成安装 （时长主要取决于网络速度）。
一、这是什么
DeepPath Knowledge 是一个部署在您自己电脑上的团队知识库与知识图谱平台。安装后通过 浏览器使用，数据完全保存在本机，不上传到任何第三方服务器。
二、安装前准备
| 项目 | 要求 |
|---|---|
| 电脑系统 | macOS（Intel 或 Apple Silicon 芯片）或 64 位 Linux |
| 内存 | 建议 8 GB 以上 |
| 磁盘空间 | 至少 10 GB 可用空间 |
| 网络 | 安装过程中需要联网下载组件 |
| 其他软件 | 无需提前安装任何软件，安装器会自动处理 |
三、选择正确的安装包
安装包是一个 .tar.gz 压缩文件，请根据您的电脑选择：
| 安装包名称 | 适用电脑 |
|---|---|
...-darwin-arm64.tar.gz |
Apple 芯片 Mac（M1/M2/M3/M4 系列） |
...-darwin-amd64.tar.gz |
Intel 芯片 Mac |
...-linux-amd64.tar.gz |
普通 64 位 Linux 电脑/服务器 |
...-linux-arm64.tar.gz |
ARM 架构 Linux 设备 |
不确定 Mac 是哪种芯片？点击屏幕左上角 → 关于本机，"芯片"一栏显示 Apple M 系列即为 arm64，显示 Intel 即为 amd64。
四、macOS 安装步骤
第 1 步：解压安装包
双击下载的 .tar.gz 文件，得到一个文件夹，里面包含：
安装 DeepPath.command（启动器）deeppath-installer（安装器主程序）images/文件夹（应用镜像）README.txt、checksums.sha256（说明与校验文件）
第 2 步：启动安装器
双击 "安装 DeepPath.command"。
如果提示"无法打开，因为无法验证开发者"： 这是 macOS 对未签名软件的正常提示，并非病毒。解决方法： 在文件上 点右键 → 选择"打开"，在弹出的对话框中再点"打开"即可。
第 3 步：按向导操作
启动后会自动打开浏览器，显示安装向导页面：
- 环境检测：页面自动检查您的系统环境，全部显示绿色"已就绪/可用"即可继续。
- 如果提示 Docker 未安装，点击 "下载并安装 Docker" 按钮，安装器会从 Docker 官网下载安装包。过程中 macOS 会弹出密码授权框，输入您的开机密码即可。 Docker 安装完成后会自动启动，首次启动需要 1–2 分钟，请耐心等待。
- 安装配置：环境就绪后出现配置表单。一般情况下无需修改任何内容，直接点击 "开始安装" 即可。
- 等待安装：页面会显示实时进度条和日志，依次完成"加载应用镜像 → 下载数据库 组件 → 启动服务 → 初始化数据库 → 健康检查"。请保持电脑联网且不要关闭终端 窗口。
- 安装完成：看到"安装完成"提示后，点击 "打开应用" 即可开始使用。
五、Linux 安装步骤
- 解压安装包：
tar -xzf deeppath-knowledge-installer-*-linux-*.tar.gz - 进入解压后的目录，运行：
./install.sh - 浏览器自动打开安装向导，后续操作与 macOS 相同。
- 如果电脑没有安装 Docker，向导会通过 Docker 官方脚本自动安装。sudo 密码请在 运行 install.sh 的终端窗口中输入（注意看终端提示），密码不会被打包或上传。
- 部分 Linux 发行版安装 Docker 后需要
注销并重新登录系统，然后再次运行
./install.sh即可继续（向导会明确提示）。
六、首次使用
安装完成打开应用后，首先看到的是创建工作区页面：
- 填写您的 姓名、工作区名称（例如团队或项目的名字）、邮箱 和 密码 （至少 8 位）。
- 点击 "创建工作区"。
- 之后即可开始导入文档（支持 PDF、DOCX、Markdown、TXT、图片和网页）、提问检索， 系统会自动构建知识图谱。
第一位注册的用户即成为该工作区的管理员。之后可在成员管理面板中生成邀请链接 （有效期 7 天），发给同事即可邀请他们加入。
七、日常使用
启动与停止
再次双击 "安装 DeepPath.command"（或 Linux 下运行
./install.sh），因为检测到
已经安装过，向导会直接显示管理页面：
| 按钮 | 作用 |
|---|---|
| 打开应用 | 在浏览器中打开 DeepPath Knowledge |
| 启动 | 启动所有服务（开机后如果服务没运行，点这里） |
| 停止 | 停止所有服务（数据不会丢失） |
| 重启 | 重启所有服务 |
| 更新 / 重新安装 | 使用新版安装包时点此升级，已有数据和配置都会保留 |
| 刷新状态 | 重新检测服务运行状态 |
访问地址
- 本机使用：
http://localhost:8080 - 局域网内其他电脑访问：
http://<您的电脑IP>:8080（安装时在"内网访问主机名或 IP" 一栏填写了本机 IP 即可）
数据保存在哪里
- 应用配置与密钥：
~/.deeppath-knowledge/目录（.env文件仅本人可读） - 文档、数据库等全部数据：保存在 Docker 数据卷中，停止服务、重启电脑、升级版本 都不会丢失
八、卸载
在终端中依次执行（卸载会删除全部数据，请谨慎操作）：
cd ~/.deeppath-knowledge
docker compose --env-file .env -f compose.yml down -v
cd ~ && rm -rf ~/.deeppath-knowledge九、常见问题
Q1：双击启动器没反应 / 提示安全性问题？
macOS：右键启动器 →"打开"。仍不行的话，打开"终端"，执行
xattr -dr com.apple.quarantine
后面跟上安装包文件夹路径（把文件夹拖进终端窗口
即可自动填入路径），回车后再双击。
Q2：向导提示"Docker 未启动"？ 打开 Docker Desktop 应用，等它状态变成 Running（鲸鱼图标静止），然后回到向导点 "重新检测"。
Q3：下载依赖镜像特别慢？ 安装时需要从 Docker Hub
下载数据库等组件。如果进度长时间卡在"下载数据库与基础服务
镜像"，说明网络到 Docker Hub 较慢。可以：① 换用更稳定的网络；②
如果您会配置 Docker 镜像加速器，在 Docker Desktop 设置 → Docker Engine
中添加 registry-mirrors 后重启 Docker，再重新安装。
Q4：提示"端口 8080 已被占用"？
说明电脑上已有其他程序占用了 8080 端口。在配置表单中把 HTTP 端口改成其他数字 （如 8081、9080），再开始安装。之后访问地址也要相应改成对应端口。
Q5：安装失败了怎么办？ 向导页面下方的黑色日志区域会显示失败原因（已自动隐藏密码等敏感信息）。修复问题后 直接重新双击启动器，点 "更新 / 重新安装" 即可继续，已下载的部分不会重复下载。
Q6：忘记密码 / 想换端口 / 换电脑迁移数据？
- 忘记密码：当前版本暂不支持自助找回，请务必妥善保管密码。如确实遗忘，需由具备 服务器操作权限的管理员在数据库中处理。
- 换端口：停止服务后，编辑
~/.deeppath-knowledge/.env中的HTTP_PORT，再点 "重启"。 - 迁移：整份拷贝
~/.deeppath-knowledge目录和 Docker 数据卷到新电脑，再运行 新电脑上的安装器即可。
Q7：安装时电脑休眠/断网了？ 重新双击启动器，进入管理页点 "更新 / 重新安装"，安装器会从中断处继续，不会 重复已完成的工作。
十、获取帮助
- 产品官网：https://deeppath.cc
- 联系邮箱：contact@deeppath.cloud