shipfe 1.1.1 → 1.1.3

package/docs/zh/features/atomic.md

@@ -1,249 +0,0 @@
-# 原子部署
-
-Shipfe 的核心特性：零停机、原子化的部署流程。
-
-## 什么是原子部署
-
-原子部署意味着部署要么完全成功，要么完全失败，没有中间状态。这确保了应用在部署过程中的稳定性。
-
-## 部署流程
-
-### 传统部署 vs 原子部署
-
-**传统部署**：
-```
-上传文件 → 覆盖现有文件 → 重启服务
-❌ 如果上传中断，应用可能处于损坏状态
-```
-
-**原子部署**：
-```
-创建新目录 → 上传到新目录 → 原子切换符号链接 → 清理旧版本
-✅ 始终有一个可用的版本
-```
-
-## 详细流程
-
-### 1. 准备阶段
-
-Shipfe 创建一个时间戳命名的发布目录：
-
-```
-releases/
-└── 20260304_120000/  # 新发布目录
-```
-
-### 2. 上传阶段
-
-所有文件上传到新目录：
-
-```bash
-# 上传构建产物
-scp -r ./dist/* user@server:/var/www/myapp/releases/20260304_120000/
-```
-
-### 3. 验证阶段
-
-验证上传的文件完整性：
-
-- 检查文件大小
-- 验证文件权限
-- 运行健康检查（如果配置）
-
-### 4. 切换阶段
-
-原子化切换当前版本：
-
-```bash
-# 在服务器上执行
-ln -sfn releases/20260304_120000 current
-```
-
-这个操作是原子的，瞬间完成。
-
-### 5. 清理阶段
-
-清理旧版本（根据配置）：
-
-```bash
-# 删除超出限制的旧版本
-rm -rf releases/20260303_100000/
-```
-
-## 零停机保证
-
-### 符号链接切换
-
-使用符号链接而不是直接覆盖文件：
-
-```
-current -> releases/20260304_120000  # 新版本
-current -> releases/20260304_110000  # 旧版本（仍然可用）
-```
-
-### 回滚能力
-
-如果新版本有问题，可以立即回滚：
-
-```bash
-# 切换回旧版本
-ln -sfn releases/20260304_110000 current
-```
-
-### 无缝切换
-
-- Web服务器继续服务旧版本
-- 用户不会察觉到切换过程
-- 新请求自动路由到新版本
-
-## 错误处理
-
-### 部署失败
-
-如果在任何阶段失败：
-
-1. **清理失败的发布目录**
-2. **保持当前版本不变**
-3. **记录详细错误信息**
-4. **应用继续正常运行**
-
-### 部分上传
-
-如果文件上传中断：
-
-- 未完成的发布目录被删除
-- 当前版本不受影响
-- 可以重新开始部署
-
-## 性能优势
-
-### 增量部署
-
-只上传变更的文件：
-
-- **首次部署**：上传所有文件
-- **后续部署**：只上传变更的文件
-- **大幅减少**：网络传输时间
-
-### 并行处理
-
-支持并行文件上传：
-
-- 多个文件同时传输
-- 充分利用带宽
-- 减少部署时间
-
-## 目录结构
-
-完整的部署目录结构：
-
-```
-remote_deploy_path/
-├── current -> releases/20260304_120000  # 当前活动版本
-├── releases/                           # 所有历史版本
-│   ├── 20260304_120000/               # 最新版本
-│   │   ├── index.html
-│   │   ├── app.js
-│   │   └── styles.css
-│   ├── 20260304_110000/               # 上一版本
-│   └── 20260304_100000/               # 更早版本
-└── shared/                            # 共享资源（可选）
-    └── assets/
-```
-
-## 配置选项
-
-### 保留版本数量
-
-```json
-{
-  "keep_releases": 5
-}
-```
-
-控制保留的历史版本数量。
-
-### 清理策略
-
-```json
-{
-  "delete_old": false  // 保留多个版本
-}
-```
-
-或
-
-```json
-{
-  "delete_old": true   // 只保留最新版本
-}
-```
-
-## 监控和日志
-
-### 部署日志
-
-每次部署都会记录详细日志：
-
-```
-2026-03-04 12:00:00 INFO  Starting deployment
-2026-03-04 12:00:01 INFO  Created release directory: releases/20260304_120000
-2026-03-04 12:00:05 INFO  Uploaded 150 files (45.2 MB)
-2026-03-04 12:00:06 INFO  Switched to new release
-2026-03-04 12:00:07 INFO  Deployment completed successfully
-```
-
-### 健康检查
-
-配置部署后的健康检查：
-
-```json
-{
-  "post_deploy_commands": [
-    "curl -f http://localhost/health || exit 1"
-  ]
-}
-```
-
-## 最佳实践
-
-1. **测试部署**：先在测试环境验证
-2. **监控日志**：实时监控部署日志
-3. **备份策略**：保留足够的历史版本
-4. **回滚计划**：准备好回滚方案
-5. **性能监控**：监控部署时间和资源使用
-
-## 故障排除
-
-### 切换失败
-
-如果符号链接切换失败：
-
-- 检查文件系统权限
-- 验证当前目录存在
-- 确认没有进程锁定文件
-
-### 权限问题
-
-确保部署用户有足够权限：
-
-```bash
-# 检查目录权限
-ls -la /var/www/myapp/
-
-# 修复权限
-chown -R deploy:deploy /var/www/myapp/
-chmod -R 755 /var/www/myapp/
-```
-
-### 磁盘空间
-
-监控磁盘使用情况：
-
-```bash
-# 检查磁盘空间
-df -h /var/www/myapp/
-
-# 清理旧版本
-shipfe deploy  # 会自动清理
-```

package/docs/zh/features/cleanup.md

@@ -1,241 +0,0 @@
-# 自动清理
-
-Shipfe 提供可配置的自动清理旧发布和未使用共享资源功能。
-
-## 配置选项
-
-### `keep_releases`（推荐）
-
-```json
-{
-  "keep_releases": 5,
-  "delete_old": false
-}
-```
-
-- 保留最近的 5 个发布
-- 自动删除旧发布
-- 与共享资源清理配合工作
-
-### `delete_old`（传统）
-
-```json
-{
-  "delete_old": true
-}
-```
-
-- 在每次部署后删除所有旧发布
-- 只保留当前部署
-- 覆盖 `keep_releases` 设置
-
-## 清理过程
-
-### 发布清理
-
-1. 按修改时间排序发布（最新优先）
-2. 保留指定数量的最近发布
-3. 完全删除旧发布目录
-
-### 共享资源清理（当 `enable_shared: true` 时）
-
-1. 扫描所有剩余发布快照
-2. 收集当前被引用的所有哈希资源
-3. 从 `shared/assets/` 删除未引用的文件
-
-## 清理行为示例
-
-### 清理前（7 个发布）
-
-```
-releases/
-├── 20260301_100000/  （最旧）
-├── 20260302_100000/
-├── 20260303_100000/
-├── 20260304_100000/
-├── 20260305_100000/
-├── 20260306_100000/
-└── 20260307_100000/  （最新，当前）
-```
-
-### 清理后（`keep_releases: 3`）
-
-```
-releases/
-├── 20260305_100000/  （保留）
-├── 20260306_100000/  （保留）
-└── 20260307_100000/  （保留，当前）
-```
-
-*旧发布自动删除*
-
-## 监控清理
-
-```bash
-# 检查当前发布
-ls -la releases/
-
-# 在 shipfe.log 中查看清理日志
-tail -f shipfe.log | grep -i "cleanup\|remove"
-```
-
-## 手动清理
-
-### 强制清理
-
-```bash
-# 重新部署会触发清理
-shipfe deploy
-```
-
-### 自定义清理脚本
-
-```bash
-#!/bin/bash
-# 自定义清理脚本示例
-
-DEPLOY_PATH="/var/www/myapp"
-KEEP_RELEASES=5
-
-# 进入发布目录
-cd "$DEPLOY_PATH/releases"
-
-# 获取要删除的旧发布
-OLD_RELEASES=$(ls -t | tail -n +$((KEEP_RELEASES + 1)))
-
-# 删除旧发布
-for release in $OLD_RELEASES; do
-  echo "Removing old release: $release"
-  rm -rf "$release"
-done
-```
-
-## 清理策略选择
-
-### 滚动发布策略
-
-```json
-{
-  "keep_releases": 5,
-  "delete_old": false
-}
-```
-
-**适用场景**：
-- 需要频繁回滚
-- 存储空间充足
-- 重视部署历史
-
-### 最小化策略
-
-```json
-{
-  "delete_old": true
-}
-```
-
-**适用场景**：
-- 存储空间有限
-- 部署频繁
-- 不需要历史版本
-
-## 共享资源清理
-
-当启用共享资源时，清理过程更复杂：
-
-1. **扫描快照**：检查所有保留发布的快照文件
-2. **收集引用**：汇总所有仍在使用的共享资源哈希
-3. **安全删除**：只删除完全未引用的共享文件
-
-### 示例清理过程
-
-```
-保留发布：v1, v2, v3
-v1 使用的共享资源：a.js, b.css
-v2 使用的共享资源：a.js, c.png
-v3 使用的共享资源：b.css, d.svg
-
-仍在使用的资源：a.js, b.css, c.png, d.svg
-可删除的资源：（无）
-
-结果：所有共享资源都被保留
-```
-
-## 性能影响
-
-### 磁盘I/O
-
-- 清理操作主要涉及文件删除
-- 对运行中的应用无影响
-- 可以在低峰期执行
-
-### 存储优化
-
-- 自动释放磁盘空间
-- 防止日志和临时文件积累
-- 维持健康的存储使用率
-
-## 安全考虑
-
-### 数据保护
-
-- 清理前验证快照完整性
-- 只删除确认未使用的文件
-- 保留最近的多个版本作为安全网
-
-### 权限检查
-
-- 验证删除权限
-- 避免删除系统文件
-- 记录所有清理操作
-
-## 故障排除
-
-### 清理失败
-
-```
-Warning: Failed to remove old release
-```
-
-**可能原因**：
-- 文件被进程锁定
-- 权限不足
-- 文件系统问题
-
-**解决方案**：
-- 检查文件锁定：`lsof +D /path/to/release`
-- 修复权限：`chmod -R 755 /var/www/myapp`
-- 手动清理：`rm -rf /path/to/old/release`
-
-### 共享资源清理问题
-
-```
-Warning: Failed to cleanup shared assets
-```
-
-**可能原因**：
-- 快照文件损坏
-- 硬链接引用错误
-- 权限问题
-
-**解决方案**：
-- 验证快照文件
-- 检查硬链接：`ls -la shared/assets/`
-- 重新生成共享资源
-
-### 磁盘空间不足
-
-如果清理无法释放足够空间：
-
-- 检查大文件：`du -sh releases/*`
-- 手动删除旧版本
-- 增加 `keep_releases` 的值
-- 考虑迁移到更大磁盘
-
-## 最佳实践
-
-1. **监控存储使用**：定期检查磁盘使用情况
-2. **设置合理保留数量**：根据部署频率调整 `keep_releases`
-3. **备份重要版本**：对关键版本进行额外备份
-4. **日志监控**：监控清理操作的日志
-5. **定期审核**：检查清理策略是否仍然合适

package/docs/zh/features/shared-assets.md

@@ -1,72 +0,0 @@
-# 共享资源管理
-
-共享资源通过文件哈希去重减少磁盘使用和网络传输。
-
-## 启用共享资源
-
-```json
-{
-  "enable_shared": true,
-  "hashed_asset_patterns": [
-    "**/*.js",
-    "**/*.css",
-    "**/*.png",
-    "**/*.jpg",
-    "**/*.svg",
-    "**/*.woff2"
-  ]
-}
-```
-
-## 工作原理
-
-1. **文件匹配**：根据 `hashed_asset_patterns` 匹配文件
-2. **哈希计算**：对匹配文件计算 SHA256 哈希值
-3. **存储策略**：
-   - 相同哈希的文件只存储一次在 `shared/assets/` 目录
-   - 文件名格式为 `{hash}.{ext}`，如 `abc123def456.js`
-4. **链接创建**：在发布目录中创建硬链接指向共享文件
-5. **清理机制**：删除不再被任何发布引用的共享文件
-
-## 共享资源重置
-
-在每次部署开始时，Shipfe 会自动清除 `shared/` 目录下的所有现有资源，然后重新创建 `shared/assets/` 目录。这确保了每次部署从干净的状态开始，避免了旧资源的积累和潜在冲突。
-
-## 目录结构示例
-
-```
-remote_deploy_path/
-├── shared/
-│   └── assets/
-│       ├── abc123def456.js
-│       ├── def789ghi012.css
-│       └── hij345klm678.png
-├── releases/
-│   ├── 20260304_120000/
-│   │   ├── index.html
-│   │   ├── app.js -> ../../shared/assets/abc123def456.js
-│   │   └── styles.css -> ../../shared/assets/def789ghi012.css
-│   └── 20260304_120100/
-│       ├── index.html
-│       ├── app.js -> ../../shared/assets/abc123def456.js
-│       └── styles.css -> ../../shared/assets/def789ghi012.css
-└── current -> releases/20260304_120100
-```
-
-## 优势
-
-- **减少磁盘使用**：相同文件只存储一次
-- **加快部署**：未更改的文件不需要重新上传
-- **节省带宽**：只传输新的或更改的文件
-- **原子更新**：所有硬链接同时创建，确保一致性
-
-## 注意事项
-
-- 共享资源需要服务器文件系统支持硬链接
-- 首次启用共享时，所有匹配文件都会被哈希处理
-- 禁用共享后，已有的共享文件不会被删除，需要手动清理
-
-## 适用场景
-
-- **启用共享**：大型应用，频繁部署，有很多静态资源
-- **禁用共享**：小型应用，部署不频繁，或需要简单调试