# 安装
本指南将帮助您在系统上安装 gflow。
## 前置要求
- **操作系统**：Linux（在 Ubuntu 20.04+ 上测试）
- **tmux**：任务执行所必需
- **NVIDIA GPU**（可选）：用于 GPU 任务调度
- **NVIDIA 驱动程序**（可选）：如果使用 GPU 功能
### 安装前置要求
#### Ubuntu/Debian
```bash
# 安装 tmux
sudo apt-get update
sudo apt-get install tmux
```
#### Fedora/RHEL
```bash
# 安装 tmux
sudo dnf install tmux
```
## 安装方法
### 方法 1：通过 PyPI 安装（推荐）
使用 `uv` 安装 gflow（推荐用于 CLI 工具）：
```bash
uv tool install runqd
```
或使用 `pipx`：
```bash
pipx install runqd
```
或使用 `pip`：
```bash
pip install runqd
```
这将为 Linux（x86_64、ARM64）安装预构建的二进制文件。
### 安装 Nightly 版本
如需体验最新开发版本，可从 TestPyPI 安装：
```bash
pip install --index-url https://test.pypi.org/simple/ runqd
```
### 方法 2：通过 Cargo 安装
从 crates.io 构建并安装：
```bash
cargo install gflow
```
或从 main 分支安装：
```bash
cargo install --git https://github.com/AndPuQing/gflow.git --locked
```
这将编译并安装所有二进制文件到 `~/.cargo/bin/`，该目录应该在您的 `PATH` 中。
### 方法 3：从源代码构建
如果您想从最新的源代码构建：
1. **克隆仓库**：
```bash
git clone https://github.com/AndPuQing/gflow.git
cd gflow
```
2. **构建项目**：
```bash
cargo build --release
```
可执行文件将位于 `target/release/` 中。
3. **安装到系统**（可选）：
```bash
cargo install --path .
```
## 验证安装
安装后，验证 gflow 是否正确安装：
```bash
# 检查命令是否可用
which gflowd ginfo gbatch gqueue gcancel
# 验证版本
gflowd --version
```
## 快速检查
### 1. 测试 tmux
确保 tmux 正常工作：
```bash
tmux new-session -d -s test
tmux has-session -t test && echo "tmux 正常工作！"
tmux kill-session -t test
```
### 2. 守护进程 + GPU 检测（可选）
如果您有 NVIDIA GPU，请验证它们是否被检测到：
```bash
# （可选）生成带有合理默认值的配置文件
gflowd init
# 启动守护进程
gflowd up
# 验证它已启动
gflowd status
```
检查系统信息和 GPU 分配：
```bash
ginfo
```
如果有可用的 NVIDIA GPU，守护进程会显示 GPU 信息。
## 文件位置
gflow 使用以下目录：
| `~/.config/gflow/gflow.toml` | 配置文件（可选） |
| `~/.local/share/gflow/state.msgpack` | 持久化任务状态（旧版本的 `state.json` 仍可读取） |
| `~/.local/share/gflow/logs/` | 任务输出日志 |
## 故障排除
### 问题：找不到命令
如果安装后出现"找不到命令"错误：
1. **检查 `~/.cargo/bin` 是否在您的 PATH 中**：
```bash
echo $PATH | grep -o ~/.cargo/bin
```
2. **如果缺失，添加到 PATH**（添加到 `~/.bashrc` 或 `~/.zshrc`）：
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
3. **重新加载 shell**：
```bash
source ~/.bashrc ```
### 问题：未检测到 GPU
1. **检查 NVIDIA 驱动程序**：
```bash
nvidia-smi
```
2. **验证 NVML 库**：
```bash
ldconfig -p | grep libnvidia-ml
```
3. 如果 GPU 检测失败，gflow 仍然可以工作，但不会管理 GPU 资源。
## 更新 gflow
### 如果通过 cargo 安装：
```bash
cargo install gflow --force
```
### 如果从源代码构建：
```bash
cd gflow
git pull
cargo build --release
cargo install --path . --force
```
## 卸载
要删除 gflow：
```bash
# 首先停止守护进程
gflowd down
# 卸载二进制文件
cargo uninstall gflow
# 删除配置和数据（可选）
rm -rf ~/.config/gflow
rm -rf ~/.local/share/gflow
```
## 下一步
现在 gflow 已安装完成，请前往[快速入门指南](./quick-start)了解如何使用它！
---