dynapm 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# 更新日志
+
+所有重要的项目变更都将记录在此文件中。
+
+格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
+版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [1.0.5] - 2025-02-10
+
+### ✨ 新增
+- 添加 CHANGELOG.md 版本更新日志
+- GitHub Release 自动从 CHANGELOG 提取发布说明
+- 优化 CI 发布流程，移除测试步骤
+
+### 📚 文档
+- 在 README 中添加完整的发布流程说明
+- 新增版本号规范说明
+
+---
+
+## [1.0.4] - 2025-02-10
+
+### 🔧 修复
+- 修复服务启动超时后状态卡死问题
+- 添加 WebSocket 背压恢复机制，防止连接永久阻塞
+- 修复服务停止时未更新状态的问题
+- 实现启动锁失败后自动重试机制
+- 清理请求头 CRLF 字符，防止 HTTP 响应分割攻击
+
+### 🎯 改进
+- 移除所有 `any` 类型，提升类型安全性
+- 提取魔法数字为 `GatewayConstants` 常量
+- 修复 `cork()` 返回值处理逻辑
+- 优化 `mkdirSync` 调用，移除不必要的 try-catch
+
+### ✨ 新增
+- 添加 GitHub Actions 自动发布到 npm 流程
+- 配置 npm OIDC 可信发布（无需 2FA）
+- 添加完整的发布说明文档
+
+### 📚 文档
+- 新增 `docs/NPM_OIDC_SETUP.md` 配置指南
+- 在 README 中添加发布新版本章节
+
+---
+
+## [1.0.3] - 2025-02-07
+
+### ✨ 新增
+- 添加活动连接计数功能
+- 实现 SSE (Server-Sent Events) 流式代理支持
+- 实现 WebSocket 双向通信代理支持
+- 添加长连接阻止服务自动停止机制
+
+### 🔧 改进
+- 优化服务启动和停止流程
+- 改进健康检查机制
+- 优化日志记录格式
+
+---
+
+## [1.0.2] - 2025-02-06
+
+### 🔧 修复
+- 修复流式代理的 backpressure 处理
+- 优化 TCP 端口检查性能
+
+### 🎯 改进
+- 使用 uWebSockets.js 替换 Express（性能提升 10 倍以上）
+- 实现真正的流式转发，零缓冲
+- 添加 Pino 结构化异步日志
+
+---
+
+## [1.0.1] - 2025-02-05
+
+### 🔧 修复
+- 修复服务启动超时检测
+- 优化闲置检查逻辑
+
+### 🎯 改进
+- 改进错误处理和日志输出
+- 优化配置加载机制
+
+---
+
+## [1.0.0] - 2025-02-04
+
+### ✨ 首次发布
+- 实现按需启动功能
+- 实现流式反向代理
+- 实现闲置自动回收
+- 支持多种健康检查方式（TCP、HTTP、命令）
+- 支持通用 bash 命令管理服务（PM2、Docker、systemd 等）
+- 添加完整的自动化测试套件
+
+---
+
+## 版本号说明
+
+- **Major** (主版本): 破坏性变更
+- **Minor** (次版本): 新功能，向后兼容
+- **Patch** (修订版): Bug 修复
+
+---
+
+## 链接
+
+- [GitHub Releases](https://github.com/2234839/DynaPM/releases)
+- [npm 包版本](https://www.npmjs.com/package/dynapm)

package/CLAUDE.md

@@ -0,0 +1,72 @@
+# DynaPM - Claude Code 项目配置
+
+DynaPM 是一个智能网关，通过按需启动和闲置自动停止的方式，帮助用户在资源受限的服务器上管理数百个低频访问的服务。
+
+**核心特性：**
+- ⚡ 极速冷启动（开销仅 25ms）
+- 🚀 流式代理（1-2ms 延迟）
+- 🌐 支持 SSE 和 WebSocket
+- 🎛️ 通用服务管理（可替代PM2、Docker、systemd 等）
+- 🔄 闲置自动回收
+
+## 技术栈
+
+- **运行时**: Node.js 22+
+- **Web 框架**: uWebSockets.js（性能比 Fastify 快 10 倍以上）
+- **日志**: Pino（异步结构化日志）
+- **配置**: c12（支持 TypeScript）
+- **构建**: rslib
+- **包管理**: pnpm
+- **测试**: tsx + 自定义测试套件
+
+## 项目结构
+
+```
+DynaPM/
+├── src/
+│   ├── core/
+│   │   ├── gateway.ts          # 核心网关实现（HTTP/WebSocket代理）
+│   │   ├── service-manager.ts  # 服务启动/停止管理
+│   │   ├── health-checker.ts    # 健康检查（TCP/HTTP/命令）
+│   │   └── command-executor.ts  # Bash 命令执行器
+│   ├── config/
+│   │   ├── types.ts             # TypeScript 类型定义
+│   │   └── loader.ts            # 配置加载器
+│   └── index.ts                 # 主入口
+├── test/
+│   ├── test-all.ts              # 完整测试套件（12个测试）
+│   ├── server-*.ts              # 测试服务器
+│   └── benchmark.js             # 性能测试
+├── docs/
+│   └── NPM_OIDC_SETUP.md        # npm OIDC 发布配置指南
+├── .github/workflows/
+│   └── release.yml              # 自动发布到 npm
+├── CHANGELOG.md                  # 版本更新日志
+├── README.md                     # 英文文档
+├── README_zh.md                  # 中文文档
+
+```
+
+## 开发指南
+
+### 快速开始
+
+```bash
+# 安装依赖
+pnpm install
+
+# 运行测试
+pnpm test
+
+# 构建项目
+pnpm build
+
+# 性能测试
+pnpm benchmark
+```
+
+### 发布新版本
+
+**⚠️ 重要：发布前必须更新 CHANGELOG.md！**
+GitHub Actions 自动发布到 npm
+详见：[CONTRIBUTING.md](./CONTRIBUTING.md)

package/CONTRIBUTING.md

@@ -0,0 +1,340 @@
+# 贡献指南
+
+感谢你有兴趣为 DynaPM 做出贡献！请阅读以下指南了解开发流程。
+
+## 📋 开发流程
+
+### 1. Fork 并克隆项目
+
+```bash
+# Fork 项目到你的 GitHub 账号
+# 然后克隆你的 fork
+git clone https://github.com/YOUR_USERNAME/DynaPM.git
+cd DynaPM
+
+# 添加上游仓库
+git remote add upstream https://github.com/2234839/DynaPM.git
+```
+
+### 2. 创建特性分支
+
+```bash
+git checkout -b feature/your-feature-name
+# 或
+git checkout -b fix/your-bug-fix
+```
+
+### 3. 开发和测试
+
+```bash
+# 安装依赖
+pnpm install
+
+# 运行测试
+pnpm test
+
+# 构建项目
+pnpm build
+```
+
+### 4. 提交更改
+
+遵循以下提交信息格式：
+
+```
+<type>: <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**类型（type）：**
+- `feat`: 新功能
+- `fix`: Bug 修复
+- `docs`: 文档更新
+- `style`: 代码格式（不影响功能）
+- `refactor`: 重构
+- `perf`: 性能优化
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+
+**示例：**
+
+```bash
+git commit -m "feat: 添加服务状态缓存功能
+
+- 使用内存缓存避免频繁执行 bash 命令
+- 优化服务状态检查性能
+
+Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>"
+```
+
+### 5. 推送到你的 Fork
+
+```bash
+git push origin feature/your-feature-name
+```
+
+### 6. 创建 Pull Request
+
+访问 GitHub 创建 PR：
+```
+https://github.com/2234839/DynaPM/compare/main...YOUR_USERNAME:feature/your-feature-name
+```
+
+---
+
+## 📦 发布版本流程
+
+**⚠️ 重要：发布版本前必须更新 CHANGELOG.md！**
+
+### 发布步骤
+
+#### 1. 更新 CHANGELOG.md
+
+在 `CHANGELOG.md` 文件**顶部**添加新版本条目：
+
+```markdown
+## [1.0.6] - 2025-02-XX
+
+### ✨ 新增
+- 新功能描述
+
+### 🔧 修复
+- Bug 修复描述
+
+### 🎯 改进
+- 改进内容描述
+
+### 📚 文档
+- 文档更新内容
+
+### ⚠️ 破坏性变更
+- 如有不兼容变更，在此说明
+
+---
+
+## [1.0.5] - 2025-02-10
+...（之前的内容）
+```
+
+#### 2. 提交 CHANGELOG
+
+```bash
+git add CHANGELOG.md
+git commit -m "chore: 添加 v1.0.6 版本更新日志"
+```
+
+#### 3. 更新版本号
+
+```bash
+# patch 版本（修复 bug）：1.0.5 -> 1.0.6
+npm version patch
+
+# minor 版本（新功能）：1.0.5 -> 1.1.0
+npm version minor
+
+# major 版本（破坏性变更）：1.0.5 -> 2.0.0
+npm version major
+```
+
+#### 4. 推送标签触发自动发布
+
+```bash
+# 推送主分支和标签
+git push origin main --tags
+```
+
+#### 5. 自动发布流程
+
+推送标签后，GitHub Actions 会自动：
+
+1. ✅ **构建项目** - 编译 TypeScript
+2. ✅ **验证打包** - 检查输出文件
+3. ✅ **发布到 npm** - 使用 OIDC 无需令牌
+4. ✅ **创建 GitHub Release** - 自动从 CHANGELOG 提取说明
+
+#### 6. 验证发布
+
+```bash
+# 查看最新版本
+npm view dynapm version
+
+# 查看 Release 说明
+# 访问：https://github.com/2234839/DynaPM/releases
+```
+
+---
+
+## 🎯 代码规范
+
+### TypeScript 规范
+
+- **禁止使用 `as` 改变类型**（尤其是 `as any`）
+- 使用 JSDoc 注释：
+  ```typescript
+  /** 服务配置 */
+  interface ServiceConfig {
+    /** 服务名称 */
+    name: string;
+  }
+  ```
+- 使用 `for of` 替代 `for i++`
+
+### 错误处理
+
+- 开发阶段使用 `let it crash` 原则
+- 不要过度使用 `try-catch`，除非功能设计需要
+- 只在系统边界（用户输入、外部 API）进行验证
+
+### 注释规范
+
+- 使用 `/** */` 形式的 JSDoc 注释
+- 注释放在变量/函数/属性的上方
+- 示例：
+  ```typescript
+  /** 检查服务是否运行中 */
+  async isRunning(service: ServiceConfig): Promise<boolean> {
+    // ...
+  }
+  ```
+
+---
+
+## 🧪 测试指南
+
+### 运行测试
+
+```bash
+# 运行完整测试套件
+pnpm test
+
+# 监听模式（开发时）
+pnpm test:watch
+```
+
+### 测试覆盖
+
+当前测试覆盖 12 个核心功能：
+1. 按需启动
+2. 热启动（服务已运行）
+3. 自动停止
+4. 404 错误处理
+5. 多服务并发
+6. 不同健康检查
+7. 路径代理
+8. 连续请求更新闲置时间
+9. POST 请求
+10. SSE 流式传输
+11. WebSocket 连接
+12. 长连接代理
+
+### 性能测试
+
+```bash
+# 运行性能测试
+pnpm benchmark
+
+# 多服务性能测试
+pnpm benchmark:multi
+```
+
+---
+
+## 📝 CHANGELOG 格式规范
+
+### 版本标题格式
+
+```markdown
+## [1.0.6] - 2025-02-10
+```
+
+### 变更类型
+
+使用以下分类（按顺序）：
+
+- **✨ 新增** (Added): 新功能
+- **🔧 修复** (Fixed): Bug 修复
+- **🎯 改进** (Changed): 现有功能的改进
+- **📚 文档** (Docs): 文档更新
+- **⚠️ 破坏性变更** (Breaking): 不兼容的变更
+- **⚡ 性能** (Performance): 性能优化
+- **🔒 安全** (Security): 安全修复
+
+### 格式要求
+
+- 每个变更前使用对应的 emoji 图标
+- 使用列表格式（`-` 开头）
+- 保持简洁明了，重点突出
+
+### 示例
+
+```markdown
+## [1.0.6] - 2025-02-10
+
+### ✨ 新增
+- 添加服务状态缓存功能
+- 支持自定义健康检查间隔
+
+### 🔧 修复
+- 修复 WebSocket 背压恢复机制
+- 修复服务启动超时后的状态卡死
+
+### 🎯 改进
+- 优化 TCP 端口检查性能
+- 改进日志输出格式
+
+### ⚠️ 破坏性变更
+- 移除 `--no-daemon` 选项（请使用 systemd 或 PM2）
+
+---
+
+## [1.0.5] - 2025-02-10
+...
+```
+
+---
+
+## 🐛 Bug 报告
+
+报告 Bug 时请提供：
+
+1. **环境信息**
+   - Node.js 版本：`node -v`
+   - DynaPM 版本：`dynapm --version`（或 `npm info dynapm version`）
+   - 操作系统
+
+2. **重现步骤**
+   - 配置文件
+   - 执行的命令
+   - 预期行为 vs 实际行为
+
+3. **日志**
+   - `logs/dynapm.log` 中的相关错误信息
+
+在 [GitHub Issues](https://github.com/2234839/DynaPM/issues) 提交问题。
+
+---
+
+## 💡 功能建议
+
+功能建议请包含：
+
+1. **使用场景** - 这个功能解决什么问题？
+2. **实现建议** - 你认为应该如何实现？
+3. **替代方案** - 是否有其他方式达到同样目的？
+
+在 [GitHub Discussions](https://github.com/2234839/DynaPM/discussions) 讨论想法。
+
+---
+
+## 📧 联系方式
+
+- 👤 **作者**: 崮生
+- 🐛 **Bug 报告**: [GitHub Issues](https://github.com/2234839/DynaPM/issues)
+- 💡 **功能建议**: [GitHub Discussions](https://github.com/2234839/DynaPM/discussions)
+
+---
+
+**感谢你的贡献！** 🎉

package/DEV.md

@@ -1,15 +1,19 @@
-## 在本地测试程序安装到全局的效果
-
-```bash
-pnpm link -g
-```
-
-## 发布到 npm
-登录一次即可
-```sh
- npm login --registry=https://registry.npmjs.org
-```
-
-```sh
-pnpm publish2npm
-```
+# 开发文档
+2
+## 在本地测试程序安装到全局的效果
+
+```bash
+pnpm link -g
+```
+
+## 发布到 npm
+登录一次即可
+```sh
+ npm login --registry=https://registry.npmjs.org
+```
+
+```sh
+pnpm publish2npm
+```
+
+## 开发指南

package/LICENSE

@@ -1,15 +1,15 @@
-ISC License
-
-Copyright (c) [2025], [崮生,shenzilong.cn]
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ISC License
+
+Copyright (c) [2025], [崮生,shenzilong.cn]
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.