shipfe 1.1.1 → 1.1.3

package/docs/zh/commands/deploy.md

@@ -1,127 +0,0 @@
-# deploy 命令
-
-执行应用部署到远程服务器。
-
-## 语法
-
-```bash
-shipfe deploy [options]
-```
-
-## 描述
-
-`deploy` 命令执行完整的部署流程：
-1. 执行构建命令（如果配置了）
-2. 创建新的发布目录
-3. 上传文件到服务器
-4. 原子化切换到新版本
-5. 清理旧版本（根据配置）
-
-## 选项
-
-| 选项 | 描述 |
-|------|------|
-| `-c, --config <file>` | 指定配置文件路径 |
-| `-d, --debug` | 启用调试模式，显示详细日志 |
-| `--dry-run` | 预览模式，不实际执行部署 |
-| `--skip-build` | 跳过构建步骤 |
-| `-h, --help` | 显示帮助信息 |
-
-## 示例
-
-### 基本部署
-
-```bash
-shipfe deploy
-```
-
-使用默认配置文件执行完整部署。
-
-### 指定配置文件
-
-```bash
-shipfe deploy --config production.json
-```
-
-使用特定的配置文件进行部署。
-
-### 调试模式
-
-```bash
-shipfe deploy --debug
-```
-
-启用详细日志输出，帮助诊断问题。
-
-### 预览部署
-
-```bash
-shipfe deploy --dry-run
-```
-
-显示将要执行的操作，但不实际部署。
-
-### 跳过构建
-
-```bash
-shipfe deploy --skip-build
-```
-
-如果构建已手动完成，可以跳过构建步骤。
-
-## 部署流程
-
-### 1. 构建阶段
-
-如果配置了 `build_command`，Shipfe会执行它：
-
-```bash
-npm run build
-# 或其他构建命令
-```
-
-### 2. 准备阶段
-
-- 创建时间戳目录：`releases/YYYYMMDD_HHMMSS`
-- 生成部署快照
-
-### 3. 上传阶段
-
-- 上传构建产物到新发布目录
-- 处理共享资源（如果启用）
-
-### 4. 切换阶段
-
-- 原子化切换 `current` 符号链接
-- 确保零停机部署
-
-### 5. 清理阶段
-
-- 删除超出 `keep_releases` 限制的旧版本
-- 清理未使用的共享资源
-
-## 部署目录结构
-
-```
-remote_path/
-├── current -> releases/20260304_120000  # 当前版本
-├── releases/
-│   ├── 20260304_120000/                # 最新版本
-│   ├── 20260304_110000/                # 上一版本
-│   └── 20260304_100000/                # 更早版本
-└── shared/                             # 共享资源（可选）
-    └── assets/
-```
-
-## 错误处理
-
-部署过程中如果出现错误：
-
-- 自动清理失败的发布目录
-- 不影响当前运行的版本
-- 详细的错误日志输出
-
-## 相关命令
-
-- [`init`](/zh/commands/init) - 初始化配置文件
-- [`rollback`](/zh/commands/rollback) - 回滚部署

package/docs/zh/commands/init.md

@@ -1,76 +0,0 @@
-# init 命令
-
-初始化Shipfe配置文件。
-
-## 语法
-
-```bash
-shipfe init [options]
-```
-
-## 描述
-
-`init` 命令在当前目录创建 `shipfe.config.json` 配置文件。这个文件包含了部署所需的所有配置信息。
-
-## 选项
-
-| 选项 | 描述 |
-|------|------|
-| `-f, --force` | 强制覆盖已存在的配置文件 |
-| `-h, --help` | 显示帮助信息 |
-
-## 示例
-
-### 基本初始化
-
-```bash
-shipfe init
-```
-
-这将在当前目录创建 `shipfe.config.json` 文件。
-
-### 强制覆盖
-
-```bash
-shipfe init --force
-```
-
-如果配置文件已存在，将被覆盖。
-
-## 生成的配置文件
-
-`init` 命令会生成一个包含默认值的配置文件：
-
-```json
-{
-  "remote_host": "",
-  "remote_user": "",
-  "remote_path": "",
-  "local_path": "./dist",
-  "keep_releases": 5,
-  "build_command": "",
-  "delete_old": false,
-  "enable_shared": false,
-  "hashed_asset_patterns": [
-    "**/*.js",
-    "**/*.css",
-    "**/*.png",
-    "**/*.jpg",
-    "**/*.svg",
-    "**/*.woff2"
-  ]
-}
-```
-
-## 下一步
-
-创建配置文件后，您需要：
-
-1. 编辑配置文件，填入您的服务器信息
-2. 配置SSH密钥认证
-3. 运行 `shipfe deploy` 进行首次部署
-
-## 相关命令
-
-- [`deploy`](/zh/commands/deploy) - 执行部署
-- [`rollback`](/zh/commands/rollback) - 回滚到上一版本

package/docs/zh/commands/rollback.md

@@ -1,115 +0,0 @@
-# rollback 命令
-
-回滚到之前的部署版本。
-
-## 语法
-
-```bash
-shipfe rollback [options] [version]
-```
-
-## 描述
-
-`rollback` 命令将应用回滚到指定的历史版本。如果不指定版本，则回滚到上一个版本。
-
-## 选项
-
-| 选项 | 描述 |
-|------|------|
-| `-c, --config <file>` | 指定配置文件路径 |
-| `-d, --debug` | 启用调试模式 |
-| `--dry-run` | 预览模式，不实际执行回滚 |
-| `-h, --help` | 显示帮助信息 |
-
-## 参数
-
-- `version`: 可选，要回滚到的版本号（时间戳格式，如 `20260304_120000`）
-
-## 示例
-
-### 回滚到上一版本
-
-```bash
-shipfe rollback
-```
-
-自动回滚到最近的稳定版本。
-
-### 回滚到指定版本
-
-```bash
-shipfe rollback 20260304_120000
-```
-
-回滚到特定的历史版本。
-
-### 预览回滚
-
-```bash
-shipfe rollback --dry-run
-```
-
-显示将要回滚到的版本，但不实际执行。
-
-## 回滚流程
-
-### 1. 版本选择
-
-- 如果指定了版本，直接使用
-- 如果未指定，自动选择最新的可用版本（非当前版本）
-
-### 2. 验证检查
-
-- 检查目标版本是否存在
-- 验证快照文件的完整性
-- 确保版本文件未损坏
-
-### 3. 原子切换
-
-- 切换 `current` 符号链接到目标版本
-- 确保切换的原子性
-
-### 4. 状态验证
-
-- 验证切换后的符号链接正确
-- 检查应用是否正常运行
-
-## 查看可用版本
-
-要查看可回滚的版本：
-
-```bash
-# SSH到服务器查看
-ssh user@server "ls -la /var/www/myapp/releases/"
-
-# 或使用shipfe日志
-tail -f shipfe.log
-```
-
-## 回滚历史
-
-每次回滚都会记录在日志中：
-
-```
-2026-03-04 12:01:00 INFO  Starting rollback to version 20260304_110000
-2026-03-04 12:01:01 INFO  Successfully rolled back to version 20260304_110000
-```
-
-## 注意事项
-
-- 回滚不会删除任何版本，只改变当前链接
-- 可以多次回滚到不同版本
-- 回滚操作是可逆的，可以再次部署新版本
-
-## 错误处理
-
-如果回滚失败：
-
-- 当前版本保持不变
-- 详细错误信息输出
-- 不会影响应用的可用性
-
-## 相关命令
-
-- [`deploy`](/zh/commands/deploy) - 执行新部署
-- [`init`](/zh/commands/init) - 初始化配置

package/docs/zh/config/auth.md

@@ -1,195 +0,0 @@
-# 认证配置
-
-配置SSH认证以安全连接到远程服务器。
-
-## SSH密钥认证（推荐）
-
-Shipfe 使用SSH密钥认证，这是最安全和最方便的方式。
-
-### 生成SSH密钥
-
-如果还没有SSH密钥：
-
-```bash
-# 生成RSA密钥（推荐）
-ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
-
-# 或生成Ed25519密钥（更现代）
-ssh-keygen -t ed25519 -C "your-email@example.com"
-```
-
-### 配置密钥路径
-
-在 `shipfe.config.json` 中指定私钥路径：
-
-```json
-{
-  "ssh_key_path": "~/.ssh/id_rsa"
-}
-```
-
-默认路径是 `~/.ssh/id_rsa`。
-
-### 添加公钥到服务器
-
-将公钥添加到服务器的 `authorized_keys`：
-
-```bash
-# 自动添加（推荐）
-ssh-copy-id user@your-server.com
-
-# 或手动添加
-cat ~/.ssh/id_rsa.pub | ssh user@server "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
-```
-
-### 验证SSH连接
-
-测试SSH连接是否正常：
-
-```bash
-ssh -i ~/.ssh/id_rsa user@your-server.com
-```
-
-## SSH端口配置
-
-如果SSH服务使用非标准端口：
-
-```json
-{
-  "ssh_port": 2222
-}
-```
-
-## 密钥权限
-
-确保SSH密钥文件权限正确：
-
-```bash
-# 私钥权限
-chmod 600 ~/.ssh/id_rsa
-
-# 公钥权限
-chmod 644 ~/.ssh/id_rsa.pub
-
-# .ssh目录权限
-chmod 700 ~/.ssh
-```
-
-## 使用不同的密钥
-
-为不同项目或环境使用不同的SSH密钥：
-
-```json
-{
-  "ssh_key_path": "~/.ssh/project_deploy_key"
-}
-```
-
-## SSH代理转发
-
-如果使用SSH代理，可以配置代理转发：
-
-```bash
-# 在本地启用代理
-eval "$(ssh-agent -s)"
-ssh-add ~/.ssh/id_rsa
-
-# 配置转发（在shipfe配置中不需要特殊设置）
-```
-
-## 密码认证（不推荐）
-
-虽然不推荐，但也可以使用密码认证：
-
-**注意**：密码认证不够安全，建议使用SSH密钥。
-
-如果必须使用密码，Shipfe会提示输入密码。
-
-## 多服务器部署
-
-为多个服务器配置不同的认证：
-
-```json
-// staging.json
-{
-  "remote_host": "staging.example.com",
-  "remote_user": "deploy",
-  "ssh_key_path": "~/.ssh/staging_key"
-}
-
-// production.json
-{
-  "remote_host": "production.example.com",
-  "remote_user": "deploy",
-  "ssh_key_path": "~/.ssh/production_key"
-}
-```
-
-## 故障排除
-
-### 权限拒绝错误
-
-```
-Permission denied (publickey)
-```
-
-**解决方案**：
-
-1. 检查私钥路径是否正确
-2. 验证公钥是否已添加到服务器
-3. 检查密钥文件权限
-4. 测试直接SSH连接
-
-### 主机密钥验证失败
-
-```
-Host key verification failed
-```
-
-**解决方案**：
-
-```bash
-# 添加主机密钥到known_hosts
-ssh-keyscan your-server.com >> ~/.ssh/known_hosts
-
-# 或禁用严格检查（不推荐）
-# 在~/.ssh/config中添加：
-# Host your-server.com
-#   StrictHostKeyChecking no
-```
-
-### SSH连接超时
-
-```
-Connection timed out
-```
-
-**解决方案**：
-
-1. 检查服务器是否可达
-2. 验证防火墙设置
-3. 确认SSH服务正在运行
-4. 检查网络连接
-
-### 调试SSH连接
-
-启用详细SSH调试：
-
-```bash
-ssh -v -i ~/.ssh/id_rsa user@your-server.com
-```
-
-或在Shipfe中使用调试模式：
-
-```bash
-shipfe deploy --debug
-```
-
-## 安全最佳实践
-
-1. **使用强密钥**：使用4096位RSA或Ed25519密钥
-2. **定期轮换密钥**：定期更换SSH密钥
-3. **限制密钥使用**：为特定服务器限制密钥使用
-4. **禁用密码认证**：在服务器上禁用SSH密码认证
-5. **使用SSH代理**：使用ssh-agent管理密钥
-6. **监控访问**：监控SSH登录日志

package/docs/zh/config/overview.md

@@ -1,153 +0,0 @@
-# 配置概览
-
-Shipfe 使用 JSON 格式的配置文件来定义部署行为。
-
-## 配置文件位置
-
-默认情况下，Shipfe 在项目根目录查找 `shipfe.config.json` 文件。
-
-您也可以使用 `-c` 或 `--config` 参数指定自定义配置文件：
-
-```bash
-shipfe deploy --config production.json
-```
-
-## 基本配置
-
-最小的配置文件包含服务器连接信息：
-
-```json
-{
-  "remote_host": "your-server.com",
-  "remote_user": "deploy",
-  "remote_path": "/var/www/myapp",
-  "local_path": "./dist"
-}
-```
-
-## 完整配置示例
-
-```json
-{
-  "remote_host": "your-server.com",
-  "remote_user": "deploy",
-  "remote_path": "/var/www/myapp",
-  "local_path": "./dist",
-  "build_command": "npm run build",
-  "keep_releases": 5,
-  "delete_old": false,
-  "enable_shared": true,
-  "hashed_asset_patterns": [
-    "**/*.js",
-    "**/*.css",
-    "**/*.png",
-    "**/*.jpg",
-    "**/*.svg",
-    "**/*.woff2"
-  ],
-  "exclude_patterns": [
-    "**/*.map",
-    "**/*.log"
-  ],
-  "ssh_key_path": "~/.ssh/id_rsa",
-  "ssh_port": 22,
-  "pre_deploy_commands": [
-    "sudo systemctl stop nginx"
-  ],
-  "post_deploy_commands": [
-    "sudo systemctl start nginx"
-  ]
-}
-```
-
-## 配置分类
-
-### 连接配置
-
-- [`remote_host`](/zh/config/auth) - 服务器地址
-- [`remote_user`](/zh/config/auth) - SSH用户名
-- [`ssh_key_path`](/zh/config/auth) - SSH密钥路径
-- [`ssh_port`](/zh/config/auth) - SSH端口
-
-### 路径配置
-
-- `remote_path` - 服务器部署根目录
-- `local_path` - 本地构建输出目录
-
-### 构建配置
-
-- `build_command` - 构建命令
-- `exclude_patterns` - 排除的文件模式
-
-### 部署策略
-
-- `keep_releases` - 保留的发布数量
-- `delete_old` - 是否只保留最新版本
-
-### 高级功能
-
-- [`enable_shared`](/zh/features/shared-assets) - 启用共享资源
-- `hashed_asset_patterns` - 共享资源文件模式
-- `pre_deploy_commands` - 部署前命令
-- `post_deploy_commands` - 部署后命令
-
-## 环境特定配置
-
-对于不同的部署环境，可以创建多个配置文件：
-
-```bash
-# 生产环境
-shipfe deploy --config production.json
-
-# 预发布环境
-shipfe deploy --config staging.json
-
-# 测试环境
-shipfe deploy --config test.json
-```
-
-## 配置验证
-
-Shipfe 在部署前会验证配置的正确性：
-
-- 检查必需字段
-- 验证服务器连接
-- 检查路径权限
-- 验证构建命令
-
-## 最佳实践
-
-1. **使用版本控制**：将配置文件纳入版本控制
-2. **环境分离**：为不同环境使用不同配置
-3. **敏感信息**：不要在配置文件中存储密码
-4. **权限控制**：确保配置文件权限正确（600）
-5. **备份配置**：定期备份重要的配置文件
-
-## 故障排除
-
-### 配置无效
-
-```bash
-shipfe deploy --debug
-```
-
-启用调试模式查看详细的配置验证信息。
-
-### 权限问题
-
-确保配置文件权限正确：
-
-```bash
-chmod 600 shipfe.config.json
-```
-
-### 路径问题
-
-使用绝对路径避免歧义：
-
-```json
-{
-  "local_path": "/full/path/to/dist",
-  "remote_path": "/var/www/myapp"
-}
-```