init
This commit is contained in:
zyj
558
docs/USER-GUIDE.md
Normal file
558
docs/USER-GUIDE.md
Normal file
@@ -0,0 +1,558 @@
|
||||
# DevPack 用户手册
|
||||
|
||||
> 版本：v0.1.0
|
||||
> 更新日期：2026-03-03
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [简介](#1-简介)
|
||||
2. [安装](#2-安装)
|
||||
3. [快速入门](#3-快速入门)
|
||||
4. [核心概念](#4-核心概念)
|
||||
5. [命令详解](#5-命令详解)
|
||||
6. [使用场景](#6-使用场景)
|
||||
7. [配置文件](#7-配置文件)
|
||||
8. [常见问题](#8-常见问题)
|
||||
9. [故障排除](#9-故障排除)
|
||||
|
||||
---
|
||||
|
||||
## 1. 简介
|
||||
|
||||
DevPack 是一个开发环境打包迁移工具。它可以：
|
||||
|
||||
- 🔍 **扫描** 你当前电脑上安装的开发工具、配置、环境变量等
|
||||
- 📦 **打包** 成一个可移植的 `.devpack` 文件
|
||||
- 🚀 **还原** 在另一台电脑上一键恢复完整开发环境
|
||||
|
||||
### 支持的内容
|
||||
|
||||
| 类别 | 支持的项目 |
|
||||
|------|-----------|
|
||||
| 编程语言 | Go, Node.js, Python, Java, Rust, .NET, Ruby, PHP |
|
||||
| 包管理器 | Scoop, Chocolatey, Winget, Homebrew, APT |
|
||||
| 编辑器 | VS Code (扩展+设置), JetBrains IDEs, Vim/Neovim |
|
||||
| Shell | PowerShell, Bash, Zsh, Fish, Windows Terminal |
|
||||
| 其他 | Git 配置, 环境变量, SSH 密钥, 字体 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 安装
|
||||
|
||||
### 2.1 通过 Go 安装
|
||||
|
||||
```bash
|
||||
go install github.com/user/devpack@latest
|
||||
```
|
||||
|
||||
### 2.2 通过包管理器安装
|
||||
|
||||
**Windows (Scoop):**
|
||||
```powershell
|
||||
scoop bucket add devpack https://github.com/user/devpack-bucket
|
||||
scoop install devpack
|
||||
```
|
||||
|
||||
**Windows (Chocolatey):**
|
||||
```powershell
|
||||
choco install devpack
|
||||
```
|
||||
|
||||
**macOS (Homebrew):**
|
||||
```bash
|
||||
brew tap user/devpack
|
||||
brew install devpack
|
||||
```
|
||||
|
||||
### 2.3 下载二进制文件
|
||||
|
||||
1. 前往 [GitHub Releases](https://github.com/user/devpack/releases)
|
||||
2. 下载对应你系统的压缩包
|
||||
3. 解压到一个目录（如 `C:\Tools\devpack\`）
|
||||
4. 将该目录添加到系统 PATH
|
||||
|
||||
### 2.4 验证安装
|
||||
|
||||
```bash
|
||||
devpack version
|
||||
```
|
||||
|
||||
输出示例：
|
||||
```
|
||||
DevPack v0.1.0 (commit: abc1234, built: 2026-03-03)
|
||||
OS: windows/amd64
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 快速入门
|
||||
|
||||
### 3.1 五分钟上手
|
||||
|
||||
```bash
|
||||
# 第一步：初始化
|
||||
devpack init
|
||||
|
||||
# 第二步：扫描你的环境
|
||||
devpack scan
|
||||
|
||||
# 第三步：打包
|
||||
devpack capture --name "my-env"
|
||||
|
||||
# 第四步：导出为文件（可以拷贝到 U 盘）
|
||||
devpack export my-env -o my-env.devpack
|
||||
```
|
||||
|
||||
拿到 `.devpack` 文件后，在新电脑上：
|
||||
|
||||
```bash
|
||||
# 第五步：安装 DevPack 后，导入文件
|
||||
devpack import my-env.devpack
|
||||
|
||||
# 第六步：预览将要做的更改
|
||||
devpack restore my-env --dry-run
|
||||
|
||||
# 第七步：正式还原
|
||||
devpack restore my-env
|
||||
```
|
||||
|
||||
### 3.2 推荐工作流
|
||||
|
||||
```
|
||||
旧电脑 新电脑
|
||||
────── ──────
|
||||
devpack init (安装 DevPack)
|
||||
│ │
|
||||
devpack scan │
|
||||
│ │
|
||||
devpack capture --name env │
|
||||
│ │
|
||||
devpack export env │
|
||||
│ │
|
||||
└── my-env.devpack ──(U盘)──▶ │
|
||||
│
|
||||
devpack import my-env.devpack
|
||||
│
|
||||
devpack restore env --dry-run
|
||||
│
|
||||
devpack restore env
|
||||
│
|
||||
✅ 环境就绪！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心概念
|
||||
|
||||
### 4.1 Pack（环境包）
|
||||
|
||||
Pack 是 DevPack 生成的打包文件（`.devpack` 格式）。它包含：
|
||||
- **Manifest** — 描述包内容的清单
|
||||
- **采集器数据** — 各个采集器收集的环境数据
|
||||
- **校验信息** — 确保文件完整性
|
||||
|
||||
一个 Pack 代表某一时刻你的开发环境的"快照"。
|
||||
|
||||
### 4.2 Profile（配置方案）
|
||||
|
||||
Profile 定义了"打包什么"和"怎么打包"。通过 Profile，你可以：
|
||||
- 只打包特定的工具链（如只打包 Go + VS Code）
|
||||
- 排除不需要的内容
|
||||
- 为不同场景准备不同的配置方案
|
||||
|
||||
内置 Profile 模板：
|
||||
| 模板 | 包含内容 |
|
||||
|------|---------|
|
||||
| `minimal` | 只有编辑器设置和 Shell 配置 |
|
||||
| `standard` | 运行时 + 编辑器 + Shell + Git + 环境变量 |
|
||||
| `full` | 所有可用的采集器 |
|
||||
|
||||
### 4.3 Collector（采集器）
|
||||
|
||||
采集器是负责扫描和收集特定类型环境信息的模块。每个采集器独立工作：
|
||||
|
||||
| 采集器 | 扫描内容 | 还原方式 |
|
||||
|--------|---------|---------|
|
||||
| `go` | Go 版本、go env、GOPATH/bin 工具 | 下载安装器 |
|
||||
| `node` | Node 版本、npm 全局包 | nvm/直接安装 |
|
||||
| `python` | Python 版本、pip 全局包 | 安装器/pyenv |
|
||||
| `vscode` | 扩展列表、settings.json | code --install-extension |
|
||||
| `powershell` | Profile、已安装模块 | 复制 Profile + Install-Module |
|
||||
| `scoop` | bucket 列表、已安装包 | scoop install |
|
||||
| `git` | .gitconfig、aliases | 复制配置 |
|
||||
| `env` | 用户环境变量 | setx/export |
|
||||
|
||||
### 4.4 还原策略
|
||||
|
||||
当还原时遇到已存在的配置，DevPack 提供多种处理策略：
|
||||
|
||||
| 策略 | 行为 |
|
||||
|------|------|
|
||||
| `skip` | 跳过，保留现有配置 |
|
||||
| `overwrite` | 覆盖，使用 Pack 中的配置 |
|
||||
| `merge` | 合并两者（适用于配置文件） |
|
||||
| `prompt` | 逐项询问用户（默认） |
|
||||
| `newest` | 使用较新的版本 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 命令详解
|
||||
|
||||
### 5.1 devpack init
|
||||
|
||||
初始化 DevPack 配置。
|
||||
|
||||
```bash
|
||||
# 默认初始化
|
||||
devpack init
|
||||
|
||||
# 使用 standard 模板
|
||||
devpack init --template standard
|
||||
|
||||
# 指定 Profile 名称
|
||||
devpack init --profile my-profile
|
||||
```
|
||||
|
||||
这会在 `~/.devpack/` 下创建配置目录和默认配置文件。
|
||||
|
||||
### 5.2 devpack scan
|
||||
|
||||
扫描当前环境，展示检测到的开发工具和配置。
|
||||
|
||||
```bash
|
||||
# 扫描所有
|
||||
devpack scan
|
||||
|
||||
# 详细模式
|
||||
devpack scan --detailed
|
||||
|
||||
# 只扫描运行时
|
||||
devpack scan --category runtime
|
||||
|
||||
# 只扫描特定采集器
|
||||
devpack scan -c go,node,vscode
|
||||
|
||||
# 输出为 JSON
|
||||
devpack scan -o json
|
||||
|
||||
# 保存扫描结果
|
||||
devpack scan --save my-scan.json
|
||||
```
|
||||
|
||||
### 5.3 devpack capture
|
||||
|
||||
捕获环境数据并创建 Pack。
|
||||
|
||||
```bash
|
||||
# 基本用法
|
||||
devpack capture --name "my-env"
|
||||
|
||||
# 使用 Profile
|
||||
devpack capture --name "go-env" --profile golang-dev
|
||||
|
||||
# 捕获所有
|
||||
devpack capture --name "full-env" --all
|
||||
|
||||
# 只捕获特定采集器
|
||||
devpack capture --name "editor-env" -c vscode,git
|
||||
|
||||
# 带描述和标签
|
||||
devpack capture --name "v1" \
|
||||
--description "生产环境工具链" \
|
||||
--tag golang,production
|
||||
```
|
||||
|
||||
### 5.4 devpack restore
|
||||
|
||||
从 Pack 还原环境。
|
||||
|
||||
```bash
|
||||
# 先预览
|
||||
devpack restore my-env --dry-run
|
||||
|
||||
# 执行还原
|
||||
devpack restore my-env
|
||||
|
||||
# 跳过冲突项
|
||||
devpack restore my-env --conflict skip
|
||||
|
||||
# 覆盖所有冲突
|
||||
devpack restore my-env --conflict overwrite
|
||||
|
||||
# 只还原特定采集器
|
||||
devpack restore my-env -c vscode,git
|
||||
|
||||
# 跳过确认
|
||||
devpack restore my-env -y
|
||||
```
|
||||
|
||||
### 5.5 devpack export / import
|
||||
|
||||
```bash
|
||||
# 导出为文件
|
||||
devpack export my-env -o ~/Desktop/my-env.devpack
|
||||
|
||||
# 导入文件
|
||||
devpack import ~/Desktop/my-env.devpack
|
||||
|
||||
# 导入并指定名称
|
||||
devpack import ~/Desktop/my-env.devpack --name imported-env
|
||||
|
||||
# 导入前验证
|
||||
devpack import ~/Desktop/my-env.devpack --verify
|
||||
```
|
||||
|
||||
### 5.6 devpack diff
|
||||
|
||||
对比环境差异。
|
||||
|
||||
```bash
|
||||
# 与当前环境对比
|
||||
devpack diff my-env --current
|
||||
|
||||
# 两个 Pack 对比
|
||||
devpack diff old-env --with new-env
|
||||
|
||||
# 只对比特定采集器
|
||||
devpack diff my-env --current -c runtime
|
||||
```
|
||||
|
||||
### 5.7 devpack list
|
||||
|
||||
```bash
|
||||
# 列出所有 Pack
|
||||
devpack list packs
|
||||
|
||||
# 列出所有 Profile
|
||||
devpack list profiles
|
||||
|
||||
# 列出所有可用采集器
|
||||
devpack list collectors
|
||||
|
||||
# 详细信息
|
||||
devpack list packs --detailed
|
||||
```
|
||||
|
||||
### 5.8 devpack profile
|
||||
|
||||
```bash
|
||||
# 创建 Profile
|
||||
devpack profile create my-profile
|
||||
|
||||
# 查看 Profile
|
||||
devpack profile show my-profile
|
||||
|
||||
# 编辑 Profile（使用默认编辑器打开）
|
||||
devpack profile edit my-profile
|
||||
|
||||
# 设置默认 Profile
|
||||
devpack profile use my-profile
|
||||
|
||||
# 删除 Profile
|
||||
devpack profile delete my-profile
|
||||
|
||||
# 列出所有 Profile
|
||||
devpack profile list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 使用场景
|
||||
|
||||
### 6.1 个人换电脑
|
||||
|
||||
**场景：** 你买了一台新笔记本电脑，需要迁移开发环境。
|
||||
|
||||
**步骤：**
|
||||
|
||||
在旧电脑上：
|
||||
```bash
|
||||
devpack init
|
||||
devpack scan --detailed # 确认要迁移的内容
|
||||
devpack capture --name "laptop-2026" --all
|
||||
devpack export laptop-2026 -o laptop-2026.devpack
|
||||
```
|
||||
|
||||
将 `laptop-2026.devpack` 拷贝到 U 盘或通过网络传到新电脑。
|
||||
|
||||
在新电脑上：
|
||||
```bash
|
||||
# 先安装 DevPack
|
||||
devpack import laptop-2026.devpack
|
||||
devpack restore laptop-2026 --dry-run # 预览
|
||||
devpack restore laptop-2026 # 开始还原
|
||||
```
|
||||
|
||||
### 6.2 团队环境统一
|
||||
|
||||
**场景：** 你是 Tech Lead，需要为团队准备统一的开发环境。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. 创建团队 Profile：
|
||||
```bash
|
||||
devpack profile create team-standard
|
||||
devpack profile edit team-standard
|
||||
```
|
||||
|
||||
2. 在 Profile 中定义标准配置（编辑 YAML 文件）
|
||||
|
||||
3. 使用 Profile 打包：
|
||||
```bash
|
||||
devpack capture --name "team-env-v1" --profile team-standard
|
||||
devpack export team-env-v1 -o team-env-v1.devpack
|
||||
```
|
||||
|
||||
4. 分发给团队成员
|
||||
|
||||
5. 成员还原：
|
||||
```bash
|
||||
devpack import team-env-v1.devpack
|
||||
devpack restore team-env-v1
|
||||
```
|
||||
|
||||
### 6.3 项目环境隔离
|
||||
|
||||
**场景：** 你同时参与 Go 和 Python 项目，需要不同的环境配置。
|
||||
|
||||
**步骤：**
|
||||
|
||||
1. 为每个项目创建 Profile：
|
||||
```bash
|
||||
devpack profile create golang-project
|
||||
devpack profile create python-ml
|
||||
```
|
||||
|
||||
2. 分别配置各 Profile 只包含对应工具链
|
||||
|
||||
3. 按项目打包：
|
||||
```bash
|
||||
devpack capture --name "go-env" --profile golang-project
|
||||
devpack capture --name "ml-env" --profile python-ml
|
||||
```
|
||||
|
||||
### 6.4 环境排障
|
||||
|
||||
**场景：** 同事说"在我电脑上能跑"，你需要对比环境差异。
|
||||
|
||||
```bash
|
||||
# 让同事导出环境
|
||||
# (同事) devpack capture --name "alice-env" && devpack export alice-env
|
||||
|
||||
# 你导入并对比
|
||||
devpack import alice-env.devpack
|
||||
devpack diff alice-env --current
|
||||
```
|
||||
|
||||
差异输出会清晰展示两个环境的不同之处。
|
||||
|
||||
---
|
||||
|
||||
## 7. 配置文件
|
||||
|
||||
### 7.1 配置文件位置
|
||||
|
||||
| 文件 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| 全局配置 | `~/.devpack/config.yaml` | DevPack 全局设置 |
|
||||
| Profile | `~/.devpack/profiles/<name>.yaml` | 命名配置方案 |
|
||||
| 日志 | `~/.devpack/logs/devpack.log` | 运行日志 |
|
||||
| Pack 存储 | `~/.devpack/packs/` | 本地 Pack 存储 |
|
||||
|
||||
### 7.2 自定义配置示例
|
||||
|
||||
```yaml
|
||||
# ~/.devpack/config.yaml
|
||||
|
||||
defaults:
|
||||
profile: "standard"
|
||||
compression: "gzip"
|
||||
conflict_strategy: "prompt"
|
||||
|
||||
logging:
|
||||
level: "info"
|
||||
|
||||
ui:
|
||||
color: true
|
||||
progress_bar: true
|
||||
|
||||
security:
|
||||
scan_for_secrets: true
|
||||
exclude_patterns:
|
||||
- "*_KEY"
|
||||
- "*_SECRET"
|
||||
- "*_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 常见问题
|
||||
|
||||
### Q: DevPack 和 Docker 有什么区别？
|
||||
|
||||
Docker 用于打包**应用运行环境**，应用运行在容器中；DevPack 用于打包**开发者的本地开发环境**，直接还原到宿主机。两者是互补关系。
|
||||
|
||||
### Q: 支持跨操作系统迁移吗？
|
||||
|
||||
不支持。DevPack 只支持同一操作系统之间的迁移（Windows → Windows, macOS → macOS）。不同操作系统的工具链和配置差异太大，无法可靠地自动转换。
|
||||
|
||||
### Q: 还原会覆盖我现有的配置吗？
|
||||
|
||||
默认不会。DevPack 使用 `prompt` 策略，遇到冲突会询问你如何处理。你也可以先使用 `--dry-run` 预览所有更改。
|
||||
|
||||
### Q: Pack 文件大小一般多大？
|
||||
|
||||
典型的开发环境 Pack 大小在 5-50 MB 之间。Pack 文件只包含配置信息和元数据，不包含实际的安装程序二进制文件（还原时会从网络下载）。
|
||||
|
||||
### Q: 密码和密钥安全吗？
|
||||
|
||||
DevPack 默认不采集 SSH 密钥和密码。如果你选择采集 SSH 密钥，它们会使用 AES-256-GCM 加密存储。DevPack 不会采集浏览器密码、系统凭证等隐私数据。
|
||||
|
||||
### Q: 还原需要网络连接吗？
|
||||
|
||||
是的。还原过程需要从网络下载对应版本的安装程序。Pack 文件只包含"安装什么"的信息，不包含安装程序本身。
|
||||
|
||||
### Q: 还原失败了怎么办？
|
||||
|
||||
如果开启了还原点功能（默认开启），可以使用 `devpack rollback` 撤销所有更改，回到还原前的状态。
|
||||
|
||||
---
|
||||
|
||||
## 9. 故障排除
|
||||
|
||||
### 9.1 查看详细日志
|
||||
|
||||
```bash
|
||||
# 开启详细输出
|
||||
devpack scan --verbose
|
||||
|
||||
# 开启 debug 日志
|
||||
devpack scan --log-level debug
|
||||
|
||||
# 查看日志文件
|
||||
# Windows
|
||||
notepad %USERPROFILE%\.devpack\logs\devpack.log
|
||||
# macOS/Linux
|
||||
cat ~/.devpack/logs/devpack.log
|
||||
```
|
||||
|
||||
### 9.2 常见错误
|
||||
|
||||
| 错误 | 原因 | 解决方案 |
|
||||
|------|------|---------|
|
||||
| `collector not available` | 对应的工具未安装 | 安装对应工具或排除该采集器 |
|
||||
| `pack file corrupted` | Pack 文件损坏 | 使用 `devpack verify` 检查，重新导出 |
|
||||
| `platform mismatch` | Pack 的系统与当前不一致 | 只能在相同 OS 之间还原 |
|
||||
| `permission denied` | 权限不足 | 以管理员身份运行 |
|
||||
| `network timeout` | 下载超时 | 检查网络，或设置代理 |
|
||||
|
||||
### 9.3 报告问题
|
||||
|
||||
如果遇到无法解决的问题：
|
||||
|
||||
1. 运行 `devpack scan --log-level debug --save debug-info.json`
|
||||
2. 查看 `~/.devpack/logs/devpack.log`
|
||||
3. 在 [GitHub Issues](https://github.com/user/devpack/issues) 创建 Issue
|
||||
4. 附上 debug 日志（注意删除敏感信息）
|
||||
Reference in New Issue
Block a user