furniture-3d-system-Wu/scripts/README.md

# 脚本使用说明

## 📋 脚本列表

### 0. 协作规则文档（当前默认）
**状态**：当前默认采用“直接开发 + 强制规范审查闸门”。
**目的**：只保留当前默认开发流程与规范审查门禁。

**配套文档**：
- `docs/workflow/审查闸门使用指南.md`
- `docs/workflow/最简执行卡片.md`
- `docs/workflow/提示词模板.md`
- `docs/workflow/规范审查清单.md`

---

### 1. 快速启动 (`quick-start.ps1`)
**用途**：一键启动开发环境

**使用方法**：
```powershell
.\scripts\quick-start.ps1
```

**功能**：
- ✅ 检查 Docker 是否运行
- ✅ 检查 VHDX 文件大小
- ✅ 启动所有 Docker 服务
- ✅ 显示访问地址
- ✅ 可选打开浏览器

---

### 2. Docker 清理 (`docker-cleanup.ps1`)
**用途**：清理 Docker 数据，释放空间

**使用方法**：
```powershell
.\scripts\docker-cleanup.ps1
```

**功能**：
- 🗑️ 清理停止的容器
- 🗑️ 清理未使用的镜像
- 🗑️ 清理未使用的卷
- 🗑️ 清理构建缓存
- 📊 显示清理前后对比
- ⚠️ 检查 VHDX 文件大小

**建议频率**：每周运行一次

---

### 3. VHDX 压缩 (`docker-compress-vhdx.ps1`)
**用途**：压缩 Docker 虚拟磁盘文件

**使用方法**：
```powershell
.\scripts\docker-compress-vhdx.ps1
```

**功能**：
- 🛑 停止 Docker Desktop
- 🗜️ 压缩 VHDX 文件
- 📊 显示节省的空间
- 🔄 可选重启 Docker

**注意事项**：
- ⚠️ 此操作会停止 Docker Desktop
- ⚠️ 压缩过程可能需要几分钟
- ⚠️ 建议在 VHDX 文件超过 50GB 时运行

---

### 4. Docker 监控 (`docker-monitor.ps1`)
**用途**：实时监控 Docker 资源使用

**使用方法**：
```powershell
.\scripts\docker-monitor.ps1
```

**功能**：
- 📊 实时显示容器状态
- 📊 实时显示 CPU 和内存使用
- 📊 实时显示磁盘使用
- 📊 实时显示 VHDX 文件大小
- 🔄 每 5 秒自动刷新

**退出方法**：按 `Ctrl+C`

---

### 5. 设置自动清理 (`setup-auto-cleanup.ps1`)
**用途**：创建 Windows 计划任务，自动清理 Docker

**使用方法**：
```powershell
# 以管理员身份运行
.\scripts\setup-auto-cleanup.ps1
```

**功能**：
- ⏰ 创建计划任务
- ⏰ 每周日凌晨 2:00 自动运行
- ⏰ 自动清理 Docker 数据

**注意事项**：
- ⚠️ 需要管理员权限
- ⚠️ 右键点击 PowerShell，选择"以管理员身份运行"

---

## 🚀 快速开始

### 首次使用

1. **设置自动清理**（推荐）
   ```powershell
   # 以管理员身份运行
   .\scripts\setup-auto-cleanup.ps1
   ```

2. **启动开发环境**
   ```powershell
   .\scripts\quick-start.ps1
   ```

3. **监控资源使用**（可选）
   ```powershell
   .\scripts\docker-monitor.ps1
   ```

### 日常使用

**启动开发环境**：
```powershell
.\scripts\quick-start.ps1
```

**停止开发环境**：
```powershell
docker-compose -f docker-compose.dev.yml down
```

**查看日志**：
```powershell
docker-compose -f docker-compose.dev.yml logs -f
```

### 维护

**每周清理**（如果没有设置自动清理）：
```powershell
.\scripts\docker-cleanup.ps1
```

**VHDX 文件过大时**（超过 50GB）：
```powershell
.\scripts\docker-compress-vhdx.ps1
```

---

## 📊 监控建议

### VHDX 文件大小警告级别

| 大小 | 状态 | 建议操作 |
|------|------|----------|
| < 20GB | ✅ 正常 | 无需操作 |
| 20-50GB | ⚠️ 注意 | 建议运行清理脚本 |
| > 50GB | 🔴 警告 | 立即运行清理和压缩脚本 |

### 定期检查

建议每周运行一次监控脚本，检查资源使用情况：
```powershell
.\scripts\docker-monitor.ps1
```

---

## 🛠️ 故障排查

### 问题 1：脚本无法运行

**错误信息**：`无法加载文件，因为在此系统上禁止运行脚本`

**解决方案**：
```powershell
# 以管理员身份运行
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

### 问题 2：Docker 未启动

**错误信息**：`Docker 未安装或未启动`

**解决方案**：
1. 打开 Docker Desktop
2. 等待 Docker 完全启动
3. 重新运行脚本

### 问题 3：VHDX 文件无法压缩

**错误信息**：`另一个程序正在使用此文件`

**解决方案**：
1. 确保 Docker Desktop 已完全关闭
2. 运行 `wsl --shutdown`
3. 等待 5 秒
4. 重新运行压缩脚本

---

## 📝 注意事项

1. **管理员权限**：某些脚本需要管理员权限才能运行
2. **数据备份**：清理和压缩操作不会删除重要数据，但建议定期备份
3. **运行时间**：压缩操作可能需要几分钟，请耐心等待
4. **自动清理**：设置自动清理后，系统会在每周日凌晨 2:00 自动运行

---

## 🔗 相关文档

- [开发部署计划](../开发部署计划.md)
- [架构更新说明](../架构更新说明.md)
- [项目架构设计文档](../项目架构设计文档.md)