WinJin 服务器管理技能

版本: v2.0.0 更新日期: 2026-01-23 模式: 手动管理（用户操作，AI 仅提供建议）重要: ⭐ 模式变更（2026-01-23）- AI 不再主动管理服务器

核心原则

模式: 手动管理（用户操作，AI 仅提供建议）

为什么采用手动管理？ ⭐ 重要变更 (2026-01-23)

•AI 通过脚本管理服务不够智能，容易出问题
•用户手动控制更可靠、更灵活
•避免意外的服务中断或数据丢失

AI职责:

•✅ 提供服务器管理建议
•✅ 说明脚本的使用方法
•✅ 解释错误信息
•✅ 回答用户问题
•❌ 不运行服务器管理脚本
•❌ 不执行启动/停止命令
•❌ 不主动检查服务器状态

用户职责:

•📋 手动运行启动脚本（start-dev.bat / start-dev.sh）
•📋 手动运行停止脚本（stop-dev.bat / stop-dev.sh）
•📋 手动重启服务器（代码修改后）
•📋 查看服务器日志和状态
•📋 遇到问题时询问 AI 获取建议

🚨 核心安全警告 ⭐⭐⭐ 最高优先级

⚠️ 禁止的命令（会导致 Claude Code 崩溃）

❌ 绝对禁止:

bash

# ❌ 危险：会杀掉所有 Node.js 进程，包括 Claude Code 自身！
taskkill /F /IM node.exe          # Windows
killall node                       # Linux/Mac
pkill -9 node                      # Linux/Mac

原因:

•这些命令会杀掉所有 Node.js 进程
•Claude Code 本身是用 Node.js 构建的
•执行后会导致 Claude Code 立即崩溃退出
•用户需要重新启动 Claude Code

真实案例 (2026-01-23):

code

用户请求: "停止当前服务"
AI 执行: taskkill /F /IM node.exe
结果: Claude Code 立即崩溃，用户需要重新进入

✅ 正确的停止方式

方案1: 使用脚本（推荐） ⭐

bash

# Windows
stop-dev.bat

# Linux/Mac
./stop-dev.sh

方案2: 只停止特定端口的进程

bash

# Windows - 查找并停止 9000 端口的进程
netstat -ano | findstr ":9000" | findstr "LISTENING"
taskkill /F /PID <进程ID>

# Linux/Mac - 查找并停止 9000 端口的进程
lsof -ti :9000
kill -9 $(lsof -ti :9000)

方案3: Ctrl+C（如果进程在当前终端运行）

bash

# 在运行服务的终端按 Ctrl+C

🚨 其他危险命令

❌ 也可能导致问题的命令:

bash

# ❌ 危险：强制终止所有进程
taskkill /F /IM *           # Windows
kill -9 -1                  # Linux/Mac

# ❌ 危险：删除所有文件
rm -rf *                    # Linux/Mac
del *.*                     # Windows

✅ 安全检查清单

在执行任何涉及进程或文件的命令前，必须检查：

• 命令是否会影响 Claude Code 自身？
• 命令是否会影响其他重要进程？
• 是否有更安全的替代方案？
• 是否已通知用户并得到确认？

记住: 当不确定时，优先使用脚本或询问用户！

服务器架构

后端服务器（Express 9000）

职责:

•提供 Sora2 API 代理
•处理视频生成请求
•管理角色库
•存储历史记录

重要: ⚠️ 代码修改后必须重启（Node.js模块缓存）

日志示例:

code

[Sora2Client] 初始化 Sora2 客户端
[Server] Express 服务器运行在端口 9000
[Video] 创建视频任务: task-123

前端服务器（Vite 5173）

职责:

•提供工作流画布（React Flow）
•开发服务器热重载

重要: ✅ 自动热重载，无需重启

日志示例:

code

VITE v7.2.4  ready in 500 ms

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose

快速启动

Windows 用户 ⭐ 推荐

bash

start-dev.bat

自动完成:

•✅ 检查环境（Node.js、npm、.env）
•✅ 检查端口占用（9000、5173）
•✅ 清理占用端口（需确认）
•✅ 启动后端和前端服务器
•✅ 打开浏览器到 http://localhost:5173/

Linux/Mac 用户

bash

./start-dev.sh

功能同Windows版本，自动完成相同的步骤。

用户操作指南

场景1: 启动开发环境

用户操作:

bash

# Windows 用户
start-dev.bat

# Linux/Mac 用户
./start-dev.sh

AI 辅助:

•解释脚本的功能
•说明脚本执行后的预期结果
•帮助排查启动失败的问题

场景2: 停止开发环境

用户操作:

bash

# Windows 用户
stop-dev.bat

# Linux/Mac 用户
./stop-dev.sh

AI 辅助:

•提醒用户停止前保存工作
•解释停止失败的可能原因
•提供手动清理端口的命令

场景3: 后端代码修改后重启

用户操作:

bash

# Windows 用户
stop-dev.bat
start-dev.bat

# Linux/Mac 用户
./stop-dev.sh
./start-dev.sh

AI 辅助:

•提醒用户后端代码修改需要重启
•说明为什么前端不需要重启
•帮助验证新代码是否生效

场景4: 端口被占用

用户操作:

bash

# Windows 用户
stop-dev.bat

# Linux/Mac 用户
./stop-dev.sh

AI 辅助:

•解释端口被占用的原因
•提供查找占用进程的命令
•提供手动清理端口的命令

问题1: 后端代码修改不生效

症状: 修改后端代码后，刷新浏览器看到的是旧代码

AI诊断:

javascript

// 1. 检查是否重启
"后端代码修改后需要重启服务器"
"是否已重启？"

// 2. 检查日志
"查看后端日志，确认新代码已加载"
"应该看到调试信息"

// 3. 提供解决方案
"运行 stop-dev.bat 停止"
"运行 start-dev.bat 重新启动"
"确认日志显示调试信息"

问题2: 端口被占用无法清理

症状: stop-dev.bat 无法终止进程

AI诊断:

javascript

// 1. 手动查找进程
Windows:
  netstat -ano | findstr :9000
  taskkill /F /PID <进程ID>

Linux/Mac:
  lsof -i :9000
  kill -9 <进程ID>

// 2. 如果仍无法清理
"可能是僵尸进程，尝试重启系统"

问题3: 前端热重载失败

症状: 修改前端代码后，浏览器没有自动刷新

AI诊断:

javascript

// 1. 手动刷新浏览器
"尝试按 F5 刷新浏览器"

// 2. 如果仍失败
"前端服务器可能需要重启"
"运行 stop-dev.bat 停止"
"运行 start-dev.bat 重新启动"

脚本命令参考

Windows

脚本	功能	使用场景
`start-dev.bat`	启动开发环境	首次启动、重启
`stop-dev.bat`	停止开发环境	端口占用、清理环境

Linux/Mac

脚本	功能	使用场景
`./start-dev.sh`	启动开发环境	首次启动、重启
`./stop-dev.sh`	停止开发环境	端口占用、清理环境

手动命令（降级方案）

⚠️ 注意: 优先使用脚本，以下命令仅在脚本不可用时使用

检查端口状态

bash

# Windows
netstat -ano | findstr ":9000"

# Linux/Mac
lsof -i :9000

终止进程

bash

# Windows
taskkill /F /PID <进程ID>

# Linux/Mac
kill -9 <进程ID>

启动服务器

bash

# 后端（终端1）
npm run server

# 前端（终端2）
cd src/client
npm run dev

验证清单

AI执行操作后，应该验证以下项目：

启动成功验证

• 后端端口 9000 正在监听
• 前端端口 5173 正在监听
• 后端日志显示调试信息
• 浏览器自动打开（如适用）
• 控制台无错误信息

停止成功验证

• 端口 9000 已释放
• 端口 5173 已释放
• 无 node.exe 进程残留

重启成功验证

• 旧进程已完全终止
• 新进程正常运行
• 后端日志显示新代码的调试信息
• 前端可以正常访问

常见问题FAQ

Q1: 为什么必须使用脚本？

A: 脚本自动化处理了很多复杂操作：

•✅ 自动检查环境（Node.js、npm、.env）
•✅ 自动清理端口占用
•✅ 自动打开浏览器
•✅ 避免手动操作的遗漏和错误

Q2: 脚本执行失败怎么办？

•查看错误信息
•检查是否已安装 Node.js
•检查 .env 文件是否存在
•尝试手动执行降级命令

Q3: 为什么后端需要重启而前端不需要？

•后端: Node.js 使用模块缓存，修改代码后需要重启
•前端: Vite 支持热重载（HMR），代码修改后自动生效

Q4: 如何确认后端已重启成功？

A: 查看后端日志，应该看到调试信息：

code

[Sora2Client] 初始化 Sora2 客户端
[Server] Express 服务器运行在端口 9000

如果看不到这些日志，说明还是旧代码在运行。

最佳实践

开发时的工作流

code

┌─────────────────────────────────────┐
│  终端 1: 运行 start-dev.bat          │
│  自动启动后端 + 前端                 │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  浏览器: 访问 http://localhost:5173/ │
│  开始开发和测试                      │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  修改后端代码？                      │
│  → 运行 stop-dev.bat + start-dev.bat │
│  → 验证日志显示调试信息              │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  修改前端代码？                      │
│  → Vite 自动热重载 ✅                │
│  → 如果失败，按 F5 刷新浏览器        │
└─────────────────────────────────────┘

AI 协助模式

主动检查: AI 应该主动检查服务器状态

•检测代码修改
•检测端口占用
•检测服务异常

询问确认: AI 应该询问用户后再执行

•是否启动服务器
•是否重启服务器
•是否清理端口

验证结果: AI 应该验证操作结果

•检查端口状态
•检查日志输出
•检查控制台错误

WinJin 服务器管理技能

核心原则

🚨 核心安全警告 ⭐⭐⭐ 最高优先级

⚠️ 禁止的命令（会导致 Claude Code 崩溃）

✅ 正确的停止方式

🚨 其他危险命令

✅ 安全检查清单

服务器架构

后端服务器（Express 9000）

前端服务器（Vite 5173）

快速启动

Windows 用户 ⭐ 推荐

Linux/Mac 用户

用户操作指南

场景1: 启动开发环境

场景2: 停止开发环境

场景3: 后端代码修改后重启

场景4: 端口被占用

脚本命令参考

Windows

Linux/Mac

手动命令（降级方案）

检查端口状态

终止进程

启动服务器

验证清单

启动成功验证

停止成功验证

重启成功验证

常见问题FAQ

Q1: 为什么必须使用脚本？

Q2: 脚本执行失败怎么办？

Q3: 为什么后端需要重启而前端不需要？

Q4: 如何确认后端已重启成功？

最佳实践

开发时的工作流

AI 协助模式

相关文档

上层文档

并行文档