shipfe 1.0.2 → 1.1.0

package/README.md

@@ -1,5 +1,9 @@
 # Shipfe
 
+[![npm version](https://img.shields.io/npm/v/shipfe.svg)](https://www.npmjs.com/package/shipfe)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/badge/GitHub-Master--Jian/shipfe--rust-blue.svg)](https://github.com/Master-Jian/shipfe-rust)
+
 A powerful, **free**, **Rust-based** deployment tool for web applications that **never requests network** and enables **one-click static frontend deployment** to servers. Supports multiple environments and sub-environments with zero-downtime atomic deployments.
 
 ## Key Features
@@ -13,6 +17,10 @@ A powerful, **free**, **Rust-based** deployment tool for web applications that *
 - 📦 **Sub-Environment Support**: Deploy multiple apps to the same server
 - 🔑 **Flexible Authentication**: SSH key, password, or environment variable authentication
 - 📝 **Detailed Logging**: Comprehensive deployment logs for troubleshooting
+- 🗂️ **Shared Asset Management**: Deduplicate hashed static assets across releases
+- 📊 **Resource Snapshot**: Generate deployment snapshots with file manifests
+- 🧹 **Automatic Cleanup**: Configurable retention of old releases and unused assets
+- 🗑️ **Shared Asset Reset**: Automatically clear all shared assets on deployment for clean state
 
 ## Installation
 
@@ -83,11 +91,14 @@ Edit `shipfe.config.json` to configure your deployment settings:
           "host": "dev.example.com",
           "port": 22,
           "username": "deploy",
-          "remote_deploy_path": "/var/www/dev",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/dev"
         }
       ],
-      "remote_tmp": "/tmp"
+      "remote_tmp": "/tmp",
+      "hashed_asset_patterns": ["assets/"],
+      "enable_shared": true,
+      "keep_releases": 5,
+      "delete_old": false
     }
   }
 }
@@ -115,27 +126,24 @@ Each server can have its own authentication method. Shipfe tries authentication
           "port": 22,
           "username": "deploy",
           "password": "web1_password",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         },
         {
           "host": "web2.prod.com",
           "port": 22,
           "username": "deploy",
           "key_path": "/home/user/.ssh/web2_key",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         },
         {
           "host": "web3.prod.com",
           "port": 22,
           "username": "deploy",
-          "key_path": "/home/user/.ssh/web3_key",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         }
       ],
-      "remote_tmp": "/tmp"
+      "remote_tmp": "/tmp",
+      "delete_old": false
     }
   }
 }
@@ -155,11 +163,14 @@ For deploying multiple applications or different configurations to the same serv
           "host": "dev.example.com",
           "port": 22,
           "username": "deploy",
-          "remote_deploy_path": "/var/www/dev",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/dev"
         }
       ],
       "remote_tmp": "/tmp",
+      "hashed_asset_patterns": ["assets/"],
+      "enable_shared": true,
+      "keep_releases": 5,
+      "delete_old": false,
       "sub_environments": {
         "admin": {
           "build_command": "npm run build:admin",
@@ -189,14 +200,411 @@ shipfe deploy --profile dev-cu
 shipfe deploy --profile dev --all-sub
 ```
 
-### Deploy all sub-environments at once
+### Configuration Details
+
+Here are all available configuration options in `shipfe.config.json`:
+
+#### Global Configuration Options
+
+- **`enable_shared`** (boolean, default: false)
+  - Enable shared asset management
+  - When enabled, matching files are hashed and stored in a shared directory to avoid re-uploading duplicates
+  - Suitable for applications with frequent deployments and many static assets
+
+- **`hashed_asset_patterns`** (array of strings, default: [])
+  - File patterns for assets that should be hashed and shared
+  - Supports glob patterns like `"**/*.js"`, `"**/*.css"`, `"**/*.{png,jpg,svg}"`
+  - Only matching files will be hashed and shared; others are uploaded fresh each deployment
+
+- **`keep_releases`** (number, default: 10)
+  - Number of release versions to keep
+  - Older releases beyond this number will be automatically cleaned up
+  - Set to 0 to disable automatic cleanup
+
+#### Environment Configuration Options
+
+Each environment (like `dev`, `prod`) can contain these options:
+
+- **`build_command`** (string, required)
+  - Local build command, e.g., `"npm run build"` or `"yarn build"`
+
+- **`local_dist_path`** (string, required)
+  - Local build output directory path, e.g., `"./dist"` or `"./build"`
+
+- **`servers`** (array of objects, required)
+  - List of servers, each containing:
+    - **`host`** (string, required): Server hostname or IP address
+    - **`port`** (number, default: 22): SSH port
+    - **`username`** (string, required): SSH username
+    - **`password`** (string, optional): SSH password (not recommended, use keys instead)
+    - **`key_path`** (string, optional): Path to SSH private key file
+    - **`remote_deploy_path`** (string, required): Deployment directory path on server
+
+- **`remote_tmp`** (string, default: "/tmp")
+  - Temporary directory path on server for file uploads
+
+- **`sub_environments`** (object, optional)
+  - Sub-environment configurations, keyed by sub-environment name
+  - Sub-environments inherit parent settings but can override `build_command`, `local_dist_path`, `remote_deploy_path`
+
+- **`delete_old`** (boolean, default: false)
+  - Delete all old releases after each deployment
+  - Keep only the current deployment
+  - Overrides `keep_releases` setting
+
+#### Shared Assets and Hashing Configuration Explained
+
+**How Shared Assets Work:**
+
+1. **File Matching**: Files are matched against `hashed_asset_patterns`
+2. **Hash Calculation**: SHA256 hashes are computed for matching files
+3. **Storage Strategy**:
+   - Identical files are stored only once in the `shared/assets/` directory
+   - Filename format: `{hash}.{ext}`, e.g., `abc123def456.js`
+4. **Link Creation**: Hard links are created in release directories pointing to shared files
+5. **Cleanup**: Shared files no longer referenced by any kept release are removed
+
+**Configuration Example with Explanations:**
+
+```json
+{
+  "enable_shared": true,
+  "hashed_asset_patterns": [
+    "**/*.js",           // Match all JS files
+    "**/*.css",          // Match all CSS files
+    "**/*.{png,jpg}",    // Match PNG and JPG files
+    "!**/vendor/**"      // Exclude vendor directory (if not needed for sharing)
+  ],
+  "keep_releases": 5
+}
+```
+
+**When to Use:**
+- **Enable sharing**: Large applications, frequent deployments, many static assets
+- **Disable sharing**: Small applications, infrequent deployments, or need for simple debugging
+
+**Important Notes:**
+- Shared assets require filesystem support for hard links
+- On first enable, all matching files will be hashed
+- Disabling sharing doesn't remove existing shared files (manual cleanup required)
+
+### Shared Assets Management
+
+Shipfe supports deduplication of hashed static assets across releases to save disk space and bandwidth. When `enable_shared` is set to `true`, hashed assets are stored in a shared directory and hard-linked in each release.
+
+**Configuration:**
+```json
+{
+  "environments": {
+    "prod": {
+      "enable_shared": true,
+      "hashed_asset_patterns": ["assets/"],
+      "keep_releases": 5,
+      "delete_old": false
+    }
+  }
+}
+```
+
+**How it works:**
+1. **Asset Detection**: Automatically detects hashed files based on:
+   - User-defined patterns (e.g., `["assets/", "static/"]`)
+   - Filename format: `name-hash.ext` (e.g., `app-abc123.js`, `style-def456.css`)
+
+2. **Deduplication Process**:
+   - First deployment: Copies hashed assets to `shared/assets/`
+   - Subsequent deployments: Creates hard links to existing shared assets
+   - Same hash = same file, no duplication
+
+3. **Shared Asset Reset**: At the start of each deployment, all existing assets in the `shared/` directory are cleared to ensure a clean state, then `shared/assets/` is recreated.
+
+4. **Automatic Cleanup**: Removes unused assets when no longer referenced by any kept release
+
+**Benefits:**
+- **Disk Space**: Saves storage by eliminating duplicate hashed files
+- **Bandwidth**: Faster deployments with smaller transfer sizes
+- **Performance**: Hard links provide instant access with minimal overhead
+
+**Example Directory Structure:**
+```
+remote_deploy_path/
+├── releases/
+│   ├── 20260304_120000/
+│   │   ├── index.html
+│   │   └── assets/
+│   │       ├── app.js -> ../../../shared/assets/app-abc123.js
+│   │       └── style.css -> ../../../shared/assets/style-def456.css
+│   └── 20260304_120100/
+│       ├── index.html
+│       └── assets/
+│           ├── app.js -> ../../../shared/assets/app-abc123.js  (same file)
+│           └── style.css -> ../../../shared/assets/style-ghi789.css  (new)
+├── shared/
+│   └── assets/
+│       ├── app-abc123.js
+│       ├── style-def456.css
+│       └── style-ghi789.css
+└── current -> releases/20260304_120100
+```
+
+### Automatic Cleanup
+
+Shipfe provides configurable automatic cleanup of old releases and unused shared assets to manage disk usage efficiently.
+
+**Configuration Options:**
+
+1. **`keep_releases`** (recommended):
+   ```json
+   {
+     "keep_releases": 5,
+     "delete_old": false
+   }
+   ```
+   - Keeps the 5 most recent releases
+   - Automatically removes older releases
+   - Works with shared assets cleanup
+
+2. **`delete_old`** (legacy):
+   ```json
+   {
+     "delete_old": true
+   }
+   ```
+   - Removes ALL old releases after each deployment
+   - Only keeps the current deployment
+   - Overrides `keep_releases` setting
+
+**Cleanup Process:**
+
+1. **Release Cleanup**:
+   - Sorts releases by modification time (newest first)
+   - Keeps specified number of recent releases
+   - Removes older release directories completely
+
+2. **Shared Assets Cleanup** (when `enable_shared: true`):
+   - Scans all remaining release snapshots
+   - Collects all currently referenced hashed assets
+   - Removes unreferenced files from `shared/assets/`
+
+**Example Cleanup Behavior:**
+
+**Before cleanup (7 releases):**
+```
+releases/
+├── 20260301_100000/  (oldest)
+├── 20260302_100000/
+├── 20260303_100000/
+├── 20260304_100000/
+├── 20260305_100000/
+├── 20260306_100000/
+└── 20260307_100000/  (newest, current)
+```
+
+**After cleanup (`keep_releases: 3`):**
+```
+releases/
+├── 20260305_100000/  (kept)
+├── 20260306_100000/  (kept)
+└── 20260307_100000/  (kept, current)
+```
+*Older releases automatically removed*
+
+**Monitoring Cleanup:**
 ```bash
-shipfe deploy --profile dev --all-sub
+# Check current releases
+ls -la releases/
+
+# View cleanup logs in shipfe.log
+tail -f shipfe.log | grep -i "cleanup\|remove"
+```
+
+## Configuration Best Practices
+
+### For Production Deployments
+
+**Recommended Configuration:**
+```json
+{
+  "enable_shared": true,
+  "keep_releases": 10,
+  "hashed_asset_patterns": [
+    "**/*.js",
+    "**/*.css",
+    "**/*.png",
+    "**/*.jpg",
+    "**/*.svg",
+    "**/*.woff2"
+  ]
+}
+```
+
+**Why this works:**
+- Shared assets reduce disk usage by 60-80%
+- 10 releases provide rollback capability
+- Hashed patterns cover common static assets
+- Automatic cleanup prevents disk space issues
+
+### For Development/Staging
+
+**Recommended Configuration:**
+```json
+{
+  "enable_shared": false,
+  "keep_releases": 3,
+  "delete_old": false
+}
+```
+
+**Why this works:**
+- Faster deployments (no asset hashing)
+- Fewer releases to manage
+- Easier debugging without shared assets complexity
+
+### For Memory-Constrained Servers
+
+**Recommended Configuration:**
+```json
+{
+  "enable_shared": true,
+  "keep_releases": 2,
+  "hashed_asset_patterns": ["**/*.{js,css}"]
+}
+```
+
+**Why this works:**
+- Minimal releases reduce storage
+- Only essential assets shared
+- Balances performance and disk usage
+
+## Troubleshooting
+
+### Common Issues
+
+**1. Permission Denied Errors**
+```
+Error: Permission denied (publickey)
+```
+**Solutions:**
+- Verify SSH key is added to `~/.ssh/authorized_keys` on server
+- Check SSH key permissions: `chmod 600 ~/.ssh/id_rsa`
+- Test SSH connection: `ssh user@host`
+
+**2. Shared Assets Not Working**
+```
+Warning: Failed to create hard link for shared asset
+```
+**Solutions:**
+- Ensure `enable_shared: true` in config
+- Check server filesystem supports hard links
+- Verify write permissions on shared directory
+
+**3. Cleanup Not Working**
 ```
+Warning: Failed to remove old release
+```
+**Solutions:**
+- Check file permissions on releases directory
+- Ensure no processes are using old release files
+- Verify `keep_releases` is set correctly
+
+**4. Snapshot Creation Fails**
+```
+Error: Failed to create snapshot
+```
+**Solutions:**
+- Check available disk space
+- Verify write permissions on releases directory
+- Ensure tar command is available on server
+
+### Debug Mode
+
+Enable detailed logging:
+```bash
+shipfe deploy --debug
+```
+
+Check logs:
+```bash
+tail -f shipfe.log
+```
+
+### Performance Optimization
+
+**Slow Deployments:**
+- Enable shared assets for large static files
+- Use `hashed_asset_patterns` to target specific files
+- Consider excluding large non-changing files from patterns
+
+**High Disk Usage:**
+- Reduce `keep_releases` count
+- Enable shared assets
+- Use `delete_old: true` for single-release deployments
 
-This will deploy to all sub-environments (admin, shop, cu) in sequence.
+**Network Issues:**
+- Compress large files before deployment
+- Use faster SSH ciphers if supported
+- Consider deploying during off-peak hours
+
+### Resource Snapshots
+
+Each deployment generates a `shipfe.snapshot.json` file containing the complete manifest of deployed files and hashed assets. This snapshot provides full visibility into what was deployed and enables various operational capabilities.
+
+**Example snapshot:**
+```json
+{
+  "id": "20260303_035045",
+  "timestamp": "2026-03-03T03:50:45Z",
+  "files": [
+    "index.html",
+    "manifest.json",
+    "assets/app-abc123.js",
+    "assets/style-def456.css",
+    "assets/logo.png"
+  ],
+  "hashed_assets": [
+    "assets/app-abc123.js",
+    "assets/style-def456.css"
+  ]
+}
+```
+
+**Snapshot Fields:**
+- **`id`**: Unique deployment identifier (timestamp-based)
+- **`timestamp`**: ISO 8601 timestamp of deployment
+- **`files`**: Complete list of all deployed files
+- **`hashed_assets`**: Subset of files identified as hashed/cacheable assets
+
+**Use Cases:**
+
+1. **Deployment Verification**:
+   ```bash
+   # Check what was deployed in a specific release
+   cat releases/20260303_035045/shipfe.snapshot.json
+   ```
+
+2. **Asset Inventory**:
+   ```bash
+   # List all hashed assets across all releases
+   find releases/ -name "shipfe.snapshot.json" -exec jq -r '.hashed_assets[]' {} \; | sort | uniq
+   ```
+
+3. **Rollback Validation**:
+   ```bash
+   # Verify rollback target has expected assets
+   jq '.files[]' releases/20260303_035045/shipfe.snapshot.json
+   ```
+
+4. **Storage Analysis**:
+   ```bash
+   # Calculate deployment sizes
+   find releases/20260303_035045/ -type f -exec ls -lh {} \; | awk '{sum += $5} END {print sum}'
+   ```
 
-Sub-environments inherit settings from the parent environment and can override `build_command`, `local_dist_path`, and `remote_deploy_path`.
+**Integration with CI/CD:**
+Snapshots enable automated verification in deployment pipelines:
+- Compare deployed files against build artifacts
+- Validate asset integrity post-deployment
+- Generate deployment reports and changelogs
 
 ### Atomic Deployment
 
@@ -215,8 +623,16 @@ shipfe deploy --profile prod --atomic
 remote_deploy_path/
 ├── releases/
 │   ├── 20260303_034945/
+│   │   ├── index.html
+│   │   ├── assets/
+│   │   │   └── app.js -> ../../../shared/assets/app-abc123.js
+│   │   └── shipfe.snapshot.json
 │   ├── 20260303_035012/
 │   └── 20260303_035045/
+├── shared/
+│   └── assets/
+│       ├── app-abc123.js
+│       └── style-def456.css
 └── current -> releases/20260303_035045
 ```
 
@@ -288,6 +704,10 @@ shipfe deploy --profile prod
 - SSH-based deployment
 - Automatic backup and rollback
 - Detailed logging
+- Shared asset deduplication
+- Resource snapshot generation
+- Configurable release retention
+- Automatic cleanup of unused assets
 
 ## License
 

package/README_CN.md

@@ -1,5 +1,9 @@
 # Shipfe
 
+[![npm version](https://img.shields.io/npm/v/shipfe.svg)](https://www.npmjs.com/package/shipfe)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub](https://img.shields.io/badge/GitHub-Master--Jian/shipfe--rust-blue.svg)](https://github.com/Master-Jian/shipfe-rust)
+
 一个强大的、**免费**、**基于 Rust** 的 Web 应用部署工具，**不请求网络**，实现**一键前端静态部署包上传到服务器**。支持多环境和子环境部署，具有零停机原子部署功能。
 
 ## 主要特性
@@ -13,6 +17,10 @@
 - 📦 **子环境支持**: 在同一服务器部署多个应用
 - 🔑 **灵活认证**: SSH 密钥、密码或环境变量认证
 - 📝 **详细日志**: 全面的部署日志用于故障排除
+- 🗂️ **共享资源管理**: 跨发布版本去重哈希静态资源
+- 📊 **资源快照**: 生成包含文件清单的部署快照
+- 🧹 **自动清理**: 可配置的旧版本保留和未使用资源清理
+- 🗑️ **共享资源重置**: 部署时自动清除所有共享资源，确保干净部署
 
 ## 安装
 
@@ -115,31 +123,117 @@ shipfe rollback --profile prod-admin --to 20260303_034945
           "port": 22,
           "username": "deploy",
           "password": "web1_password",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         },
         {
           "host": "web2.prod.com",
           "port": 22,
           "username": "deploy",
           "key_path": "/home/user/.ssh/web2_key",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         },
         {
           "host": "web3.prod.com",
           "port": 22,
           "username": "deploy",
-          "remote_deploy_path": "/var/www/prod",
-          "delete_old": false
+          "remote_deploy_path": "/var/www/prod"
         }
       ],
-      "remote_tmp": "/tmp"
+      "remote_tmp": "/tmp",
+      "delete_old": false
     }
   }
 }
 ```
 
+### 配置项详解
+
+以下是 `shipfe.config.json` 中所有可用配置项的详细说明：
+
+#### 全局配置项
+
+- **`enable_shared`** (boolean, 默认: false)
+  - 是否启用共享资源管理
+  - 启用后，会对匹配的文件计算哈希并存储在共享目录中，避免重复上传
+  - 适用于频繁部署且有大量静态资源的应用
+
+- **`hashed_asset_patterns`** (array of strings, 默认: [])
+  - 指定需要哈希处理的静态资源文件模式
+  - 支持 glob 模式，如 `"**/*.js"`, `"**/*.css"`, `"**/*.{png,jpg,svg}"`
+  - 只有匹配的文件会被哈希并共享，不匹配的文件每次部署都会重新上传
+
+- **`keep_releases`** (number, 默认: 10)
+  - 保留的发布版本数量
+  - 超过此数量的旧发布会被自动清理
+  - 设置为 0 禁用自动清理
+
+#### 环境配置项
+
+每个环境（如 `dev`, `prod`）可以包含以下配置：
+
+- **`build_command`** (string, 必需)
+  - 本地构建命令，如 `"npm run build"` 或 `"yarn build"`
+
+- **`local_dist_path`** (string, 必需)
+  - 本地构建输出目录路径，如 `"./dist"` 或 `"./build"`
+
+- **`servers`** (array of objects, 必需)
+  - 服务器列表，每个服务器包含以下配置：
+    - **`host`** (string, 必需): 服务器主机名或 IP 地址
+    - **`port`** (number, 默认: 22): SSH 端口
+    - **`username`** (string, 必需): SSH 用户名
+    - **`password`** (string, 可选): SSH 密码（不推荐，建议使用密钥）
+    - **`key_path`** (string, 可选): SSH 私钥文件路径
+    - **`remote_deploy_path`** (string, 必需): 服务器上部署目录路径
+
+- **`remote_tmp`** (string, 默认: "/tmp")
+  - 服务器上的临时目录路径，用于上传文件
+
+- **`sub_environments`** (object, 可选)
+  - 子环境配置，键为子环境名称，值为子环境配置对象
+  - 子环境会继承父环境的设置，但可以覆盖 `build_command`, `local_dist_path`, `remote_deploy_path`
+
+- **`delete_old`** (boolean, 默认: false)
+  - 是否在每次部署后删除所有旧发布
+  - 只保留当前部署
+  - 覆盖 `keep_releases` 设置
+
+#### 共享资源和哈希配置说明
+
+**共享资源的工作原理：**
+
+1. **文件匹配**: 根据 `hashed_asset_patterns` 匹配文件
+2. **哈希计算**: 对匹配文件计算 SHA256 哈希值
+3. **存储策略**: 
+   - 相同哈希的文件只存储一次在 `shared/assets/` 目录
+   - 文件名格式为 `{hash}.{ext}`，如 `abc123def456.js`
+4. **链接创建**: 在发布目录中创建硬链接指向共享文件
+5. **清理机制**: 删除不再被任何发布引用的共享文件
+
+**配置示例和解释：**
+
+```json
+{
+  "enable_shared": true,
+  "hashed_asset_patterns": [
+    "**/*.js",        // 匹配所有 JS 文件
+    "**/*.css",       // 匹配所有 CSS 文件
+    "**/*.{png,jpg}", // 匹配 PNG 和 JPG 文件
+    "!**/vendor/**"   // 排除 vendor 目录（如果不需要共享）
+  ],
+  "keep_releases": 5
+}
+```
+
+**适用场景：**
+- **启用共享**: 大型应用，频繁部署，有很多静态资源
+- **禁用共享**: 小型应用，部署不频繁，或需要简单调试
+
+**注意事项：**
+- 共享资源需要服务器文件系统支持硬链接
+- 首次启用共享时，所有匹配文件都会被哈希处理
+- 禁用共享后，已有的共享文件不会被删除，需要手动清理
+
 ### 子环境
 
 对于在同一服务器部署多个应用或不同配置，使用子环境：
@@ -222,6 +316,182 @@ remote_deploy_path/
 
 您的 Web 服务器应从 `remote_deploy_path/current` 提供服务。
 
+## 共享资源管理
+
+Shipfe 支持跨多个发布版本共享静态资源，通过文件哈希去重来减少磁盘使用和网络传输。
+
+**启用共享资源：**
+```json
+{
+  "environments": {
+    "prod": {
+      "enable_shared": true,
+      "hashed_asset_patterns": [
+        "**/*.js",
+        "**/*.css",
+        "**/*.png",
+        "**/*.jpg",
+        "**/*.svg",
+        "**/*.woff2"
+      ],
+      "servers": [...]
+    }
+  }
+}
+```
+
+**工作原理：**
+
+1. **文件哈希计算**：对匹配模式的文件计算 SHA256 哈希
+2. **共享存储**：将哈希文件存储在 `shared/assets/` 目录
+3. **硬链接创建**：在发布目录中创建指向共享文件的硬链接
+4. **自动清理**：删除未被任何发布引用的共享文件
+
+**共享资源重置：**
+
+在每次部署开始时，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
+```
+
+**优势：**
+- **减少磁盘使用**：相同文件只存储一次
+- **加快部署**：未更改的文件不需要重新上传
+- **节省带宽**：只传输新的或更改的文件
+- **原子更新**：所有硬链接同时创建，确保一致性
+
+## 资源快照
+
+每个发布都会生成包含完整文件清单的快照，用于审计和回滚验证。
+
+**快照内容：**
+- 所有部署文件及其哈希值
+- 共享资源引用
+- 部署时间戳和元数据
+- 文件权限和大小信息
+
+**快照文件位置：**
+```
+releases/20260304_120100/
+├── files/
+│   ├── index.html
+│   └── app.js -> ../../shared/assets/abc123def456.js
+├── snapshot.json
+└── metadata.json
+```
+
+**快照示例：**
+```json
+{
+  "timestamp": "20260304_120100",
+  "files": {
+    "index.html": {
+      "hash": "a1b2c3d4e5f6...",
+      "size": 1024,
+      "permissions": "644"
+    },
+    "app.js": {
+      "shared_hash": "abc123def456.js",
+      "size": 51200,
+      "permissions": "644"
+    }
+  },
+  "metadata": {
+    "build_command": "npm run build",
+    "deployed_by": "user",
+    "deployed_at": "2026-03-04T12:01:00Z"
+  }
+}
+```
+
+## 自动清理
+
+Shipfe 提供可配置的自动清理旧发布和未使用共享资源功能，以有效管理磁盘使用。
+
+**配置选项：**
+
+1. **`keep_releases`**（推荐）：
+   ```json
+   {
+     "keep_releases": 5,
+     "delete_old": false
+   }
+   ```
+   - 保留最近的 5 个发布
+   - 自动删除旧发布
+   - 与共享资源清理配合工作
+
+2. **`delete_old`**（传统）：
+   ```json
+   {
+     "delete_old": true
+   }
+   ```
+   - 在每次部署后删除所有旧发布
+   - 只保留当前部署
+   - 覆盖 `keep_releases` 设置
+
+**清理过程：**
+
+1. **发布清理**：
+   - 按修改时间排序发布（最新优先）
+   - 保留指定数量的最近发布
+   - 完全删除旧发布目录
+
+2. **共享资源清理**（当 `enable_shared: true` 时）：
+   - 扫描所有剩余发布快照
+   - 收集当前被引用的所有哈希资源
+   - 从 `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
 export SSH_PRIVATE_KEY="$(cat ~/.ssh/prod_key)"
@@ -280,6 +550,133 @@ shipfe deploy --profile prod
    }
    ```
 
+## 配置最佳实践
+
+### 生产环境部署
+
+**推荐配置：**
+```json
+{
+  "enable_shared": true,
+  "keep_releases": 10,
+  "hashed_asset_patterns": [
+    "**/*.js",
+    "**/*.css",
+    "**/*.png",
+    "**/*.jpg",
+    "**/*.svg",
+    "**/*.woff2"
+  ]
+}
+```
+
+**为什么有效：**
+- 共享资源将磁盘使用减少 60-80%
+- 10 个发布提供回滚能力
+- 哈希模式覆盖常见静态资源
+- 自动清理防止磁盘空间问题
+
+### 开发/预发布环境
+
+**推荐配置：**
+```json
+{
+  "enable_shared": false,
+  "keep_releases": 3,
+  "delete_old": false
+}
+```
+
+**为什么有效：**
+- 部署更快（无资源哈希）
+- 更少的发布需要管理
+- 无共享资源复杂性，更易调试
+
+### 内存受限服务器
+
+**推荐配置：**
+```json
+{
+  "enable_shared": true,
+  "keep_releases": 2,
+  "hashed_asset_patterns": ["**/*.{js,css}"]
+}
+```
+
+**为什么有效：**
+- 最少的发布减少存储
+- 只共享必要资源
+- 平衡性能和磁盘使用
+
+## 故障排除
+
+### 常见问题
+
+**1. 权限拒绝错误**
+```
+Error: Permission denied (publickey)
+```
+**解决方案：**
+- 验证 SSH 密钥已添加到服务器的 `~/.ssh/authorized_keys`
+- 检查 SSH 密钥权限：`chmod 600 ~/.ssh/id_rsa`
+- 测试 SSH 连接：`ssh user@host`
+
+**2. 共享资源不工作**
+```
+Warning: Failed to create hard link for shared asset
+```
+**解决方案：**
+- 确保配置中 `enable_shared: true`
+- 检查服务器文件系统支持硬链接
+- 验证 shared 目录的写入权限
+
+**3. 清理不工作**
+```
+Warning: Failed to remove old release
+```
+**解决方案：**
+- 检查 releases 目录的文件权限
+- 确保没有进程正在使用旧发布文件
+- 验证 `keep_releases` 设置正确
+
+**4. 快照创建失败**
+```
+Error: Failed to create snapshot
+```
+**解决方案：**
+- 检查可用磁盘空间
+- 验证 releases 目录的写入权限
+- 确保服务器上有 tar 命令
+
+### 调试模式
+
+启用详细日志：
+```bash
+shipfe deploy --debug
+```
+
+检查日志：
+```bash
+tail -f shipfe.log
+```
+
+### 性能优化
+
+**部署缓慢：**
+- 为大静态文件启用共享资源
+- 使用 `hashed_asset_patterns` 针对特定文件
+- 考虑从模式中排除大的非更改文件
+
+**磁盘使用过高：**
+- 减少 `keep_releases` 数量
+- 启用共享资源
+- 对单发布部署使用 `delete_old: true`
+
+**网络问题：**
+- 部署前压缩大文件
+- 如果支持，使用更快的 SSH 密码
+- 考虑在非高峰时段部署
+
 ## 功能特性
 
 - 多环境支持

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shipfe",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "A deployment tool for web applications",
   "main": "index.js",
   "bin": {
@@ -23,6 +23,10 @@
     "ci-cd"
   ],
   "author": "Jans",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Master-Jian/shipfe-rust.git"
+  },
   "license": "MIT",
   "os": [
     "darwin",