⚡

LocalDevelopmentServerManagementSkill local-dev-server

为Empathy Ledger使用PM2实现零摩擦的本地开发服务器管理，解决地址已被使用错误、服务器崩溃不自动重启等问题，提供集中日志记录和简单命令操作。

DevOps 0 次安装 0 次浏览 更新于 3/1/2026

本地开发服务器管理

目的： 为Empathy Ledger使用PM2实现零摩擦的本地开发服务器管理

触发器： 当用户需要启动/停止/重启本地开发服务器，或者当“地址已被使用”错误发生时

快速命令

# 单个项目（仅Empathy Ledger）
pm2 start empathy-ledger       # 启动服务器
pm2 restart empathy-ledger     # 重启服务器
pm2 stop empathy-ledger        # 停止服务器
pm2 logs empathy-ledger        # 查看日志

# 全ACT生态系统（所有项目）
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh logs

此解决方案解决的问题

痛点：

  • ❌ 当端口被占用时出现“地址已被使用”错误
  • ❌ 忘记在代码更改后重新启动服务器
  • ❌ 服务器崩溃且不自动重启
  • ❌ 查找哪个进程正在使用端口
  • ❌ 手动npm run dev是脆弱的并不持久

解决方案：

  • ✅ PM2自动管理进程生命周期
  • ✅ 崩溃后自动重启
  • ✅ 集中日志记录
  • ✅ 与ACT生态系统部署脚本一起工作
  • ✅ 简单的开始/停止/重启命令

使用PM2与npm run dev的时机

使用PM2时：

  • 同时在多个ACT项目上工作
  • 需要在文件更改时自动重启
  • 想要跨项目的集中日志记录
  • 本地部署以进行测试
  • 服务器不断崩溃且需要持久性

使用npm run dev时：

  • 快速一次性测试
  • 使用控制台日志进行积极调试
  • 仅在Empathy Ledger上工作
  • 进行快速代码更改并希望立即反馈

设置（一次性）

1. 全局安装PM2

npm install -g pm2

2. 创建Empathy Ledger PM2配置

全局生态系统配置已在以下位置配置Empathy Ledger： /Users/benknight/act-global-infrastructure/deployment/ecosystem.config.cjs

Empathy Ledger配置：

{
  name: 'empathy-ledger',
  script: '/Users/benknight/.nvm/versions/node/v20.19.3/bin/npm',
  args: 'run dev',
  cwd: '/Users/benknight/Code/empathy-ledger-v2',
  env: {
    PORT: 3001,  // 注意：与独立模式（3030）不同
    NODE_ENV: 'development',
  },
  autorestart: true,
  max_restarts: 10,
  min_uptime: '10s',
}

使用模式

模式1：单个项目（仅Empathy Ledger）

启动服务器：

cd /Users/benknight/Code/empathy-ledger-v2
pm2 start npm --name "empathy-ledger-solo" -- run dev

检查状态：

pm2 list

查看日志：

pm2 logs empathy-ledger-solo

代码更改后重启：

pm2 restart empathy-ledger-solo

停止服务器：

pm2 stop empathy-ledger-solo
pm2 delete empathy-ledger-solo  # 从PM2中移除

模式2：完整的ACT生态系统

启动所有项目（推荐）：

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start

这将启动：

  • ACT Regenerative Studio (port 3002)
  • Empathy Ledger (port 3001)
  • JusticeHub (port 3003)
  • The Harvest Website (port 3004)
  • ACT Farm (port 3005)
  • ACT Placemat (port 3999)

全部重启：

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart

全部停止：

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop

查看所有日志：

pm2 logs

监控所有项目：

pm2 monit

模式3：修复“地址已被使用”错误

问题： 端口3030（或任何端口）被占用

解决方案1：杀死进程并使用PM2重启

# 查找并杀死端口上的进程
lsof -ti :3030 | xargs kill -9

# 使用PM2启动以实现自动恢复
pm2 start npm --name "empathy-ledger-solo" -- run dev

解决方案2：使用PM2重启（处理清理）

pm2 restart empathy-ledger

解决方案3：使用生态系统脚本

/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart

故障排除

服务器无法启动

检查PM2状态：

pm2 list
pm2 logs empathy-ledger --lines 50

检查端口可用性：

lsof -i :3030
lsof -i :3001  # 如果使用生态系统配置

强制杀死并重启：

pm2 delete empathy-ledger
lsof -ti :3030 | xargs kill -9
pm2 start npm --name "empathy-ledger-solo" -- run dev

服务器反复崩溃

检查最大重启次数：

pm2 logs empathy-ledger --err --lines 100

如果看到“达到最大重启次数”，则可能是代码错误。检查错误日志：

cat /Users/benknight/act-global-infrastructure/deployment/logs/empathy-ledger-error.log

增加最大重启次数（如果需要）： 编辑生态系统配置并将max_restarts: 10 → max_restarts: 20

代码更改未反映

PM2默认不自动重新加载

选项1：更改后手动重启：

pm2 restart empathy-ledger

选项2：启用监视模式（不推荐用于Next.js）：

pm2 start npm --name "empathy-ledger-solo" --watch -- run dev

选项3：直接使用npm run dev进行积极开发

最佳实践

开发工作流程

  1. 早晨启动：

    /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start

  2. 检查全部运行：

    pm2 list

  3. 进行代码工作（自动重启处理崩溃）

  4. 需要时查看日志：

    pm2 logs empathy-ledger

  5. 一天结束时：

    /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop

测试工作流程

  1. 进行代码更改

  2. 重启服务器：

    pm2 restart empathy-ledger

  3. 等待3-5秒启动

  4. 测试API/功能

  5. 检查日志中的错误：

    pm2 logs empathy-ledger --lines 20

与现有工具集成

与Supabase本地开发一起工作

# 启动Supabase
npx supabase start

# 使用PM2启动Empathy Ledger
pm2 start npm --name "empathy-ledger-solo" -- run dev

# 两者一起运行
pm2 list

与数据库迁移一起工作

# 运行迁移
npx supabase db push

# 重启服务器以加载新架构
pm2 restart empathy-ledger

与测试脚本一起工作

# 服务器已通过PM2运行
pm2 list

# 运行测试脚本
bash test-syndication.sh

# 如果有错误则查看日志
pm2 logs empathy-ledger --lines 30

PM2备忘单

命令 目的
pm2 start <script> 启动一个进程
pm2 list 显示所有进程
pm2 logs 查看所有日志（实时）
pm2 logs <name> 查看特定进程日志
pm2 restart <name> 重启进程
pm2 stop <name> 停止进程
pm2 delete <name> 从PM2中移除
pm2 monit 打开监控仪表板
pm2 flush 清除所有日志
pm2 save 保存当前进程列表
pm2 startup 在系统启动时启用PM2

自动化建议

创建项目特定脚本

添加到package.json：

{
  "scripts": {
    "dev": "next dev -p 3030",
    "dev:pm2": "pm2 start npm --name empathy-ledger-solo -- run dev",
    "dev:restart": "pm2 restart empathy-ledger-solo",
    "dev:stop": "pm2 stop empathy-ledger-solo && pm2 delete empathy-ledger-solo",
    "dev:logs": "pm2 logs empathy-ledger-solo"
  }
}

使用方式：

npm run dev:pm2        # 使用PM2启动
npm run dev:restart    # 重启
npm run dev:logs       # 查看日志
npm run dev:stop       # 停止并移除

在Shell中创建别名（.zshrc或.bashrc）

# Empathy Ledger快捷方式
alias el-start='pm2 start npm --name empathy-ledger-solo -- run dev'
alias el-restart='pm2 restart empathy-ledger-solo'
alias el-stop='pm2 stop empathy-ledger-solo && pm2 delete empathy-ledger-solo'
alias el-logs='pm2 logs empathy-ledger-solo'
alias el-status='pm2 list | grep empathy'

# ACT生态系统快捷方式
alias act-start='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh start'
alias act-restart='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart'
alias act-stop='/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh stop'
alias act-logs='pm2 logs'
alias act-status='pm2 list'

重新加载shell：

source ~/.zshrc  # 或source ~/.bashrc

使用方式：

el-start      # 启动Empathy Ledger
el-restart    # 重启
el-logs       # 查看日志
el-stop       # 停止

ACT生态系统部署脚本

位置： /Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh

命令：

./deploy-act-ecosystem.sh start    # 启动所有项目
./deploy-act-ecosystem.sh stop     # 停止所有项目
./deploy-act-ecosystem.sh restart  # 重启所有项目
./deploy-act-ecosystem.sh status   # 显示状态
./deploy-act-ecosystem.sh logs     # 显示所有日志
./deploy-act-ecosystem.sh monitor  # 打开PM2仪表板

功能：

  • ✅ 启动所有6个ACT项目
  • ✅ 自动在Chrome中打开网站（通过AppleScript）
  • ✅ 集中日志记录到 /Users/benknight/act-global-infrastructure/deployment/logs/
  • ✅ 崩溃后自动重启
  • ✅ 彩色状态输出

端口：

  • ACT Studio: 3002
  • Empathy Ledger: 3030
  • JusticeHub: 3003
  • Harvest: 3004
  • ACT Farm: 3005
  • Placemat: 3999

注意： 所有项目在独立和生态系统模式下使用一致的端口

常见场景

场景1：“地址已被使用”错误

用户看到：

Error: listen EADDRINUSE: address already in use :::3030

Claude响应：

# 杀死现有进程
lsof -ti :3030 | xargs kill -9

# 使用PM2启动以提高可靠性
pm2 start npm --name "empathy-ledger-solo" -- run dev

# 验证运行
pm2 list

场景2：服务器需要在架构修复后重启

用户说：“我修复了架构，现在重启服务器”

Claude响应：

# 如果使用PM2
pm2 restart empathy-ledger

# 如果使用生态系统
/Users/benknight/act-global-infrastructure/deployment/scripts/deploy-act-ecosystem.sh restart

# 等待启动
sleep 5

# 测试
curl http://localhost:3030

场景3：测试联合系统

用户说：“测试联合API”

Claude响应：

# 确保服务器正在运行
pm2 list | grep empathy || pm2 start npm --name "empathy-ledger-solo" -- run dev

# 等待启动
sleep 5

# 运行测试
bash test-syndication.sh

# 如果有错误则检查日志
pm2 logs empathy-ledger-solo --lines 50

与开发工作流程集成

冲刺开发周期

冲刺开始：

act-start  # 启动所有ACT项目

开发期间：

# 进行代码更改
# ...

# 重启以测试
pm2 restart empathy-ledger

# 查看日志
pm2 logs empathy-ledger

冲刺结束：

# 停止所有项目
act-stop

# 或者如果明天继续，则保持运行
pm2 save  # 保存当前状态

日志管理

查看实时日志：

pm2 logs empathy-ledger

查看最后N行：

pm2 logs empathy-ledger --lines 100

仅查看错误日志：

pm2 logs empathy-ledger --err

清除所有日志：

pm2 flush

日志文件位置（生态系统）：

/Users/benknight/act-global-infrastructure/deployment/logs/empathy-ledger-out.log
/Users/benknight/act-global-infrastructure/deployment/logs/empathy-ledger-error.log

当Claude应该使用这项技能时

触发短语：

  • “启动开发服务器”
  • “重启服务器”
  • “地址已被使用”
  • “端口3030忙碌”
  • “服务器无法启动”
  • “测试API”（首先确保服务器正在运行）
  • “本地部署”
  • “运行所有ACT项目”

Claude应采取的行动：

  1. 检查服务器是否正在运行：

    pm2 list | grep empathy

  2. 如果没有运行，则启动它：

    pm2 start npm --name "empathy-ledger-solo" -- run dev

  3. 如果正在运行但需要重启：

    pm2 restart empathy-ledger-solo

  4. 等待启动：

    sleep 5

  5. 验证响应：

    curl -s http://localhost:3030 > /dev/null && echo "✅ 服务器正在运行" || echo "❌ 服务器无响应"

  6. 进行测试/开发

成功标准

使用这项技能后，用户应该：

  • ✅ 服务器可靠运行
  • ✅ 能够轻松重启服务器
  • ✅ 不再有“地址已被使用”的错误
  • ✅ 访问集中日志
  • ✅ 知道如何为所有ACT项目使用PM2

这项技能通过提供一致的、可靠的、基于PM2的工作流程，消除了“本地部署狗斗”，与ACT生态系统部署策略保持一致。