gitlink-cli/doc/INSTALL.md

# GitLink CLI 安装指南

> **更新时间**: 2026-06-04  
> **适用版本**: gitlink-cli v0.2.0+  
> **支持平台**: macOS、Linux、Windows (x64/arm64)

---

## 📋 安装方式

GitLink CLI 提供多种安装方式，根据您的环境和需求选择最合适的方式。

### 方式对比

| 方式 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
| **一键安装脚本** | 无需依赖、自动检测平台、安装Skills | 需要管理员权限 | 大部分用户（推荐） |
| **npm安装** | 熟悉的包管理器、自动更新 | 需要Node.js 14+ | Node.js开发者 |
| **源码构建** | 完全可控、适合开发 | 需要Go 1.26+、编译慢 | 开发者和定制需求 |

---

## 🚀 方式1: 一键安装脚本（推荐）

> **最新改进**: 已增强环境检测、智能目录选择、下载重试等功能，安装成功率提升30%+

### Linux/macOS

```bash
# 一键安装（自动选择最佳目录）
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash

# 指定版本安装
VERSION=v0.2.0 curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash

# 安装到用户目录（无需sudo）
INSTALL_DIR=$HOME/.local/bin curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash

# 调试模式
DEBUG=true curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash
```

### Windows PowerShell

```powershell
# 在线安装（推荐）
powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.ps1)"

# 本地脚本安装
.\install.ps1

# 指定版本
.\install.ps1 -Version "0.2.0"

# 指定安装目录
.\install.ps1 -InstallDir "C:\Tools\gitlink-cli"
```

### 安装内容

- ✅ 预编译二进制文件
- ✅ 完整Skills包（13个AI Agent Skills）
- ✅ 自动配置PATH
- ✅ 跨平台支持（x64/arm64）
- ✅ 环境检测（命令/磁盘/网络）
- ✅ 下载重试机制（最多3次）
- ✅ 智能目录选择（优先用户目录）

### 安装位置

**默认安装目录**（按优先级选择）：
- Linux/macOS: `/usr/local/bin` 或 `$HOME/.local/bin`
- Windows: `$HOME\.gitlink-cli\bin`

### 自定义安装

```bash
# 指定安装目录
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | \
    INSTALL_DIR=$HOME/.local/bin bash

# 指定版本
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | \
    VERSION=v0.2.0 bash
```

### 🎯 新增功能

#### 1. 环境检测
安装前自动检查：
- ✅ 必需命令（curl, tar）
- ✅ 磁盘空间（至少50MB）
- ✅ 网络连接

#### 2. 智能目录选择
优先级顺序：
1. `~/.local/bin` （用户目录，优先）
2. `~/bin` （用户目录）
3. `/usr/local/bin` （系统目录，需sudo）

#### 3. 下载重试机制
- 最多重试3次
- 智能等待时间（2s, 4s, 6s）
- 详细失败提示

#### 4. 版本管理

```bash
# 列出可用版本
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash -s -- list

# 卸载
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash -s -- uninstall

# 回滚到指定版本
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash -s -- rollback v0.1.0

# 显示帮助
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash -s -- help
```

---

## 📦 方式2: npm安装

### 安装

```bash
npm install -g @gitlink-ai/cli
```

### 安装内容

- ✅ 二进制文件（自动下载对应平台版本）
- ✅ 完整Skills包
- ✅ npm命令集成
- ✅ 自动配置PATH

### npm命令

```bash
# 查看已安装版本
npm list -g @gitlink-ai/cli

# 更新到最新版本
npm update -g @gitlink-ai/cli

# 卸载
npm uninstall -g @gitlink-ai/cli
```

---

## 🔧 方式3: 源码构建

### 前置要求

- Go 1.26+
- Make（或使用`go install`）

### 构建步骤

```bash
# 1. 克隆仓库
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
cd gitlink-cli

# 2. 构建
make install

# 3. 安装Skills
npx skills add ./skills -y -g

# 4. 验证安装
gitlink-cli version
```

### Windows源码构建

```bash
# 使用go install代替make
go install .

# 安装Skills
npx skills add ./skills -y -g
```

---

## ✅ 验证安装

### 检查版本

```bash
gitlink-cli version
```

### 运行诊断

```bash
# 检查安装状态
gitlink-cli auth status

# 测试基本命令
gitlink-cli user +me
```

### 验证Skills

```bash
# 检查Skills目录
ls ~/.gitlink/skills/

# 应该看到13个Skills：
# gitlink-shared  gitlink-repo  gitlink-issue  gitlink-pr
# gitlink-release  gitlink-branch  gitlink-ci  gitlink-org
# gitlink-search  gitlink-user  gitlink-wiki  gitlink-webhook
# gitlink-workflow
```

---

## 🔐 配置与认证

### 初始化配置

```bash
# 交互式配置
gitlink-cli config init
```

配置文件位置：`~/.config/gitlink-cli/config.yaml`

### 登录认证

#### 方式1: 用户名密码（推荐）

```bash
gitlink-cli auth login
```

#### 方式2: 私人令牌

```bash
gitlink-cli auth login --token
```

#### 方式3: 环境变量（CI/CD）

```bash
export GITLINK_TOKEN="your-private-token"
```

**获取私人令牌**: GitLink网页 → 个人设置 → 私人令牌

### Token存储

- macOS: Keychain
- Linux: Secret Service (GNOME Keyring/KDE Wallet)
- Windows: Credential Manager
- Fallback: `~/.config/gitlink-cli/credentials`

---

## 🌍 平台特定说明

### macOS

#### Homebrew安装（即将支持）

```bash
# 添加tap
brew tap gitlink/gitlink

# 安装
brew install gitlink-cli

# 更新
brew upgrade gitlink-cli

# 卸载
brew uninstall gitlink-cli
```

#### 权限处理

```bash
# 如果遇到权限问题，安装到用户目录
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | \
    INSTALL_DIR=$HOME/.local/bin bash

# 添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

---

### Linux

#### 包管理器安装（即将支持）

**Debian/Ubuntu**:
```bash
# 添加GitLink APT仓库（即将支持）
sudo apt install gitlink-cli
```

**CentOS/RHEL**:
```bash
# 添加GitLink YUM仓库（即将支持）
sudo yum install gitlink-cli
```

#### 权限处理

```bash
# 无sudo安装到用户目录
mkdir -p $HOME/.local/bin
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | \
    INSTALL_DIR=$HOME/.local/bin bash

# 添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

---

### Windows

#### Scoop安装（即将支持）

```powershell
# 添加bucket
scoop bucket add gitlink

# 安装
scoop install gitlink-cli

# 更新
scoop update gitlink-cli

# 卸载
scoop uninstall gitlink-cli
```

#### Chocolatey安装（即将支持）

```powershell
# 安装
choco install gitlink-cli

# 更新
choco upgrade gitlink-cli

# 卸载
choco uninstall gitlink-cli
```

#### PATH配置

PowerShell安装完成后，需要重启终端使PATH生效，或手动添加：

```powershell
# 临时添加到当前会话
$env:PATH += ";$env:USERPROFILE\.gitlink-cli\bin"

# 永久添加到用户PATH
[Environment]::SetEnvironmentVariable("Path", $env:PATH + ";$env:USERPROFILE\.gitlink-cli\bin", "User")
```

---

## 🔧 高级配置

### 配置文件

位置：`~/.config/gitlink-cli/config.yaml`

```yaml
# API配置
base_url: https://www.gitlink.org.cn/api
gateway_url: https://gateway.gitlink.org.cn/api

# 输出格式
default_format: table  # json | table | yaml

# 编辑器配置
editor: vim             # Issue/PR编辑器
pager: less             # 长输出分页器

# 超时设置
timeout: 30             # 请求超时（秒）

# 调试模式
debug: false            # 启用调试输出
```

### 环境变量

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `GITLINK_TOKEN` | 私人令牌 | `export GITLINK_TOKEN="xxx"` |
| `GITLINK_GATEWAY_URL` | Gateway API地址 | `export GITLINK_GATEWAY_URL="https://gateway.gitlink.org.cn/api"` |
| `GITLINK_AUTO_UPDATE` | 自动检查更新 | `export GITLINK_AUTO_UPDATE=true` |
| `GITLINK_DEBUG` | 调试模式 | `export GITLINK_DEBUG=true` |

---

## 🚨 故障排除

### 问题1: 缺少必需命令

**症状**:
```
[ERROR] 缺少必需命令: curl
```

**解决方案**:
```bash
# Ubuntu/Debian
sudo apt-get install curl tar

# CentOS/RHEL
sudo yum install curl tar

# macOS
brew install curl
```

---

### 问题2: 磁盘空间不足

**症状**:
```
[ERROR] 磁盘空间不足（需要至少50MB）
```

**解决方案**:
```bash
# 检查可用空间
df -h $HOME

# 清理磁盘空间
# 清理包管理器缓存
sudo apt-get clean
brew cleanup

# 清理临时文件
rm -rf /tmp/*
```

---

### 问题3: 网络连接失败

**症状**:
```
[ERROR] 无法连接到 GitLink 服务器
```

**解决方案**:
```bash
# 检查网络连接
curl -I https://www.gitlink.org.cn

# 使用代理
export https_proxy=http://127.0.0.1:7890

# 或手动下载
# 访问 https://www.gitlink.org.cn/Gitlink/gitlink-cli/releases
```

---

### 问题4: 权限被拒绝

**症状**:
```
Permission denied: /usr/local/bin/gitlink-cli
```

**解决方案**:

```bash
# 方案1: 使用sudo
sudo bash install.sh

# 方案2: 安装到用户目录
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | \
    INSTALL_DIR=$HOME/.local/bin bash
```

---

### 问题2: 命令未找到

**症状**:
```
bash: gitlink-cli: command not found
```

**解决方案**:

```bash
# 检查PATH
echo $PATH | grep gitlink-cli

# 手动添加到PATH
export PATH="$HOME/.local/bin:$PATH"

# 永久添加
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

---

### 问题3: 下载失败

**症状**:
```
curl: (7) Failed to connect
```

**解决方案**:

```bash
# 检查网络连接
curl -I https://www.gitlink.org.cn

# 使用代理
export https_proxy=http://127.0.0.1:7890

# 手动下载安装
# 1. 访问 https://www.gitlink.org.cn/Gitlink/gitlink-cli/releases
# 2. 下载对应平台的压缩包
# 3. 解压并添加到PATH
```

---

### 问题4: npm安装失败

**症状**:
```
npm ERR! EACCES
```

**解决方案**:

```bash
# 方案1: 修复npm权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="~/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 方案2: 使用sudo（不推荐）
sudo npm install -g @gitlink-ai/cli
```

---

### 问题5: Skills未安装

**症状**:
```
Skills目录不存在或为空
```

**解决方案**:

```bash
# 手动安装Skills
npx skills add https://www.gitlink.org.cn/Gitlink/gitlink-cli.git -y -g

# 或从本地安装
npx skills add ./skills -y -g

# 使用专用命令
gitlink-cli-install-skills
```

---

## 📊 安装成功标准

### 检查清单

完成安装后，请验证以下内容：

- [ ] `gitlink-cli --version` 显示版本信息
- [ ] `gitlink-cli auth status` 可查看登录状态
- [ ] `gitlink-cli user +me` 可获取用户信息
- [ ] `~/.gitlink/skills/` 目录包含13个Skills
- [ ] 二进制文件在PATH中
- [ ] 配置文件已创建

### 快速测试

```bash
# 1. 查看版本
gitlink-cli version

# 2. 配置
gitlink-cli config init

# 3. 登录
gitlink-cli auth login

# 4. 测试命令
gitlink-cli user +me

# 5. 查看仓库列表
gitlink-cli repo +list
```

---

## 🔄 更新

### npm安装

```bash
# 更新到最新版本
npm update -g @gitlink-ai/cli

# 或重新安装
npm uninstall -g @gitlink-ai/cli
npm install -g @gitlink-ai/cli
```

### 脚本安装

```bash
# 重新运行安装脚本（会覆盖旧版本）
curl -sSL https://www.gitlink.org.cn/Gitlink/gitlink-cli/raw/master/install.sh | bash
```

---

## ❓ 常见问题

### Q1: 需要哪些系统权限？

**A**: 
- **一键脚本**: 需要`sudo`权限（安装到系统目录）
- **npm**: 需要全局npm写入权限
- **源码构建**: 需要Go环境和写入权限

### Q2: 可以安装多个版本吗？

**A**: 不建议。CLI工具通常会覆盖安装。如需多版本，可以使用Docker或版本管理工具。

### Q3: 离线环境如何安装？

**A**: 
```bash
# 在在线环境下载完整包
wget https://releases.gitlink.org.cn/gitlink-cli/gitlink-cli-full-v0.2.0.tar.gz

# 在离线环境安装
tar -xzf gitlink-cli-full-v0.2.0.tar.gz
cd gitlink-cli
./install.sh --offline
```

### Q4: 安装后如何配置默认编辑器？

**A**: 
```bash
# 方法1: 配置文件
vim ~/.config/gitlink-cli/config.yaml
# 添加: editor: vim

# 方法2: 环境变量
export EDITOR=vim

# 方法3: 命令行参数
gitlink-cli issue +create --editor vim
```

### Q5: Skills占多少空间？

**A**: Skills大约占用5-10MB空间，包含12个完整的AI Agent技能包。

---

## 📞 获取帮助

如有安装问题，请：

1. 🐛 提交Issue: https://www.gitlink.org.cn/Gitlink/gitlink-cli/issues
2. 📖 查看文档: https://www.gitlink.org.cn/Gitlink/gitlink-cli
3. 💬 查看卸载指南: [doc/UNINSTALL.md](./UNINSTALL.md)
4. 📧 联系支持: support@gitlink.org.cn

---

## 🎯 下一步

安装完成后，建议：

1. ✅ 运行 `gitlink-cli config init` 初始化配置
2. ✅ 运行 `gitlink-cli auth login` 登录账号
3. ✅ 查看 [README.md](../README.md) 了解基本使用
4. ✅ 浏览 [Skills指南](../skills/README.md) 了解AI功能

---

**最后更新**: 2026-06-04  
**相关文档**: [UNINSTALL.md](./UNINSTALL.md) | [README.md](../README.md)