【新增】私有证书

2026-03-08 07:41:10 +08:00 · 2025-09-03 15:15:59 +08:00
parent efd052a297
commit 954cd1638d
442 changed files with 76787 additions and 7483 deletions
--- a/frontend/.doc/plugin-sftp.md
+++ b/frontend/.doc/plugin-sftp.md
@@ -0,0 +1,150 @@
+### Vite 自动部署插件（FTP/SFTP）开发辅助方案
+
+该方案专注于为开发者提供便捷、可靠的前端项目自动部署工具，通过 Vite 插件形式集成，实现构建完成后自动上传到远程服务器，减少手动部署的重复劳动与出错概率。
+
+
+#### 一、核心价值（开发辅助定位）
+1. **无缝集成开发流程**：与 Vite 构建流程深度融合，无需离开开发环境即可完成部署
+2. **降低环境切换成本**：统一本地配置与远程部署规则，避免"本地正常，线上出错"的环境差异问题
+3. **安全管理敏感信息**：通过环境变量隔离认证信息，防止密钥泄露
+4. **可视化部署反馈**：实时展示上传进度与结果，问题定位更高效
+5. **支持多环境部署**：一键切换开发/测试/生产环境配置，适配不同阶段部署需求
+
+
+#### 二、功能模块设计
+
+##### 1. 基础配置模块
+- **核心参数**（必选）：
+  - 协议类型（`protocol: 'ftp' | 'sftp'`）
+  - 服务器地址（`host`）、端口（`port`）
+  - 认证信息（用户名+密码/私钥）
+  - 本地目录（`localDir`）与远程目录（`remoteDir`）
+
+- **环境区分配置**：
+  ```javascript
+  // 示例：多环境配置
+  environments: {
+    dev: { host: 'dev.server.com', remoteDir: '/dev' },
+    test: { host: 'test.server.com', remoteDir: '/test' },
+    prod: { host: 'prod.server.com', remoteDir: '/prod' }
+  }
+  ```
+  支持通过命令行参数（`--env=prod`）快速切换环境
+
+
+##### 2. 智能上传模块
+- **增量上传机制**：
+  - 基于文件哈希比对（默认 MD5），仅上传变更文件
+  - 本地缓存已上传文件信息（`.upload-cache`目录），提速二次部署
+  - 支持强制全量上传（`--force`命令行参数）
+
+- **文件过滤系统**：
+  - 基础过滤：glob 模式匹配（`include`/`exclude`）
+  - 高级过滤：自定义函数（如根据文件大小/类型过滤）
+  - 内置排除项：`.git`、`.DS_Store`、`.map`等开发相关文件
+
+- **传输优化**：
+  - 并发控制（默认 5 个文件同时上传，可配置）
+  - 大文件分片传输（>10MB 自动分片，支持断点续传）
+  - 传输模式自动选择（文本/二进制）
+
+
+##### 3. 开发友好特性
+- **实时反馈机制**：
+  - 进度条展示：总进度、当前文件、传输速度
+  - 详细日志输出：包含文件名、大小、状态（成功/失败）
+  - 错误提示：明确指出失败原因（权限不足/文件不存在等）
+
+- **调试辅助**：
+  - 模拟上传模式（`dryRun: true`）：仅展示上传列表，不实际传输
+  - 调试日志（`verbose: 'debug'`）：输出完整协议交互信息
+  - 本地文件校验：上传前检查本地文件完整性
+
+- **快捷操作**：
+  - 独立部署命令：`vite deploy`（无需重新构建）
+  - 配置验证命令：`vite deploy --validate`（检查配置合法性）
+  - VS Code 插件集成：提供部署按钮与状态显示
+
+
+##### 4. 安全与容错模块
+- **敏感信息保护**：
+  - 环境变量注入：`process.env.SFTP_PASSWORD`
+  - 配置加密：支持对敏感字段加密存储
+  - 日志脱敏：密码/私钥在日志中显示为`***`
+
+- **容错机制**：
+  - 自动重试：连接失败/传输超时自动重试（默认 3 次）
+  - 断线续传：网络中断恢复后继续未完成的上传
+  - 部分失败处理：单个文件失败不阻断整体流程，最终汇总失败列表
+
+
+##### 5. 扩展能力
+- **生命周期钩子**：
+  ```javascript
+  hooks: {
+    beforeDeploy: (config) => { /* 部署前执行，如备份远程文件 */ },
+    afterDeploy: (result) => { /* 部署后执行，如发送通知 */ },
+    onFileUploaded: (file) => { /* 单个文件上传完成 */ }
+  }
+  ```
+
+- **自定义处理器**：
+  - 上传前文件处理（如压缩、替换环境变量）
+  - 自定义远程操作（如上传后执行远程命令）
+
+
+#### 三、使用流程（开发视角）
+
+1. **安装配置**：
+   ```bash
+   npm i vite-plugin-deploy --save-dev
+   ```
+   ```javascript
+   // vite.config.js
+   import deploy from 'vite-plugin-deploy';
+   
+   export default {
+     plugins: [
+       deploy({
+         protocol: 'sftp',
+         host: 'your.server.com',
+         username: 'deploy',
+         privateKey: process.env.SSH_PRIVATE_KEY,
+         localDir: 'dist',
+         remoteDir: '/var/www/html',
+         environments: { /* 多环境配置 */ }
+       })
+     ]
+   }
+   ```
+
+2. **日常开发部署**：
+   ```bash
+   # 构建并部署到默认环境
+   npm run build
+   
+   # 构建并部署到测试环境
+   npm run build -- --env=test
+   
+   # 仅部署（使用上次构建结果）
+   npx vite deploy --env=prod
+   
+   # 模拟部署（不实际上传）
+   npx vite deploy --dry-run
+   ```
+
+3. **问题排查**：
+   - 查看终端输出的错误信息
+   - 启用调试模式：`npx vite deploy --verbose=debug`
+   - 检查`.upload-cache`目录的缓存文件与远程文件差异
+
+
+#### 四、优势总结（开发体验）
+1. **零学习成本**：配置简洁直观，符合前端开发者习惯
+2. **减少重复工作**：一次配置，后续部署无需重复操作
+3. **安全可靠**：避免手动操作导致的误删文件/配置错误
+4. **适配多场景**：从个人开发调试到团队生产部署均适用
+5. **可扩展性**：支持根据团队流程定制化扩展
+
+
+该方案通过聚焦开发效率与使用体验，将部署环节从"手动操作负担"转化为"自动化辅助工具"，让开发者更专注于代码开发而非部署流程。