collabdocchat 1.2.8 → 1.2.9

package/README.md

@@ -226,6 +226,20 @@ npm run serve
 
 ## 📝 更新日志
 
+### v1.2.8 (2026-01-26) - 当前版本
+- 🔧 修复 devDependencies 安装问题
+- ✨ 自动检测并安装缺失的依赖
+- 🛡️ 添加端口占用检测
+- 📚 优化 postinstall 脚本，不再自动启动服务
+- 💡 改进错误提示和用户引导
+
+### v1.2.7 (2026-01-26)
+- 📚 添加详细的 INSTALLATION.md 安装指南
+- 📝 添加 CONTRIBUTING.md 贡献指南
+
+### v1.2.6 (2026-01-26)
+- 📝 更新版本日志
+
 ### v1.2.5 (2026-01-26)
 - 🔧 修复 Windows 下 CLI 启动问题
 - 📚 优化安装和使用说明

package/USAGE.md

@@ -0,0 +1,296 @@
+# 使用说明
+
+## 🚀 推荐的安装和使用流程
+
+### 步骤 1: 安装包
+
+```bash
+# 在您想要的目录下安装
+npm install collabdocchat
+```
+
+### 步骤 2: 进入目录
+
+```bash
+cd node_modules/collabdocchat
+```
+
+### 步骤 3: 启动应用
+
+```bash
+npm start
+```
+
+**首次启动时**，系统会自动：
+- 检测并安装缺失的依赖
+- 检查端口是否可用
+- 启动服务器和客户端
+- 自动打开浏览器
+
+## ⚠️ 常见问题解决
+
+### 问题 1: 端口被占用
+
+如果看到错误：`Error: listen EADDRINUSE: address already in use :::3000`
+
+**解决方案：**
+
+#### Windows:
+```cmd
+# 查找占用端口的进程
+netstat -ano | findstr :3000
+
+# 结束进程（替换 <PID> 为实际的进程ID）
+taskkill /PID <PID> /F
+```
+
+#### Mac/Linux:
+```bash
+# 查找并结束进程
+lsof -ti:3000 | xargs kill -9
+```
+
+或者使用项目提供的停止脚本：
+```bash
+npm run stop
+```
+
+### 问题 2: vite 命令找不到
+
+如果看到错误：`'vite' 不是内部或外部命令`
+
+**原因：** 开发依赖未安装
+
+**解决方案：**
+```bash
+# 在 collabdocchat 目录下运行
+npm install
+```
+
+v1.2.8 及以上版本会在启动时自动检测并安装缺失的依赖。
+
+### 问题 3: MongoDB 连接失败
+
+如果看到错误：`MongoNetworkError: connect ECONNREFUSED`
+
+**解决方案：**
+
+1. **确保 MongoDB 已安装**
+   - 下载地址: https://www.mongodb.com/try/download/community
+
+2. **启动 MongoDB 服务**
+
+   **Windows:**
+   ```cmd
+   net start MongoDB
+   ```
+
+   **Mac:**
+   ```bash
+   brew services start mongodb-community
+   ```
+
+   **Linux:**
+   ```bash
+   sudo systemctl start mongod
+   ```
+
+3. **验证 MongoDB 运行**
+   ```bash
+   # 连接到 MongoDB
+   mongosh
+   # 或旧版本
+   mongo
+   ```
+
+## 📋 完整的使用流程示例
+
+### Windows 用户
+
+```cmd
+# 1. 创建项目目录
+mkdir my-collab-app
+cd my-collab-app
+
+# 2. 安装包
+npm install collabdocchat
+
+# 3. 进入目录
+cd node_modules\collabdocchat
+
+# 4. 确保 MongoDB 运行
+net start MongoDB
+
+# 5. 启动应用
+npm start
+```
+
+### Mac/Linux 用户
+
+```bash
+# 1. 创建项目目录
+mkdir my-collab-app
+cd my-collab-app
+
+# 2. 安装包
+npm install collabdocchat
+
+# 3. 进入目录
+cd node_modules/collabdocchat
+
+# 4. 确保 MongoDB 运行
+brew services start mongodb-community  # Mac
+# 或
+sudo systemctl start mongod  # Linux
+
+# 5. 启动应用
+npm start
+```
+
+## 🎯 访问应用
+
+启动成功后，浏览器会自动打开：
+
+- **客户端界面**: http://localhost:5173
+- **服务器 API**: http://localhost:3000
+
+### 默认管理员账号
+
+- **用户名**: `admin`
+- **密码**: `admin123`
+
+⚠️ **重要**: 首次登录后请立即修改密码！
+
+## 🛑 停止应用
+
+### 方法 1: 使用快捷键
+在运行应用的终端窗口按 `Ctrl + C`
+
+### 方法 2: 使用停止脚本
+```bash
+npm run stop
+```
+
+### 方法 3: 手动结束进程
+
+**Windows:**
+```cmd
+taskkill /F /IM node.exe
+```
+
+**Mac/Linux:**
+```bash
+pkill -f node
+```
+
+## 🔧 配置说明
+
+### 修改端口
+
+编辑 `.env` 文件：
+
+```env
+# 修改服务器端口
+PORT=3000
+
+# MongoDB 连接
+MONGODB_URI=mongodb://localhost:27017/collabdocchat
+
+# JWT 密钥（生产环境务必修改）
+JWT_SECRET=your-secret-key-here
+```
+
+### 修改管理员账号
+
+编辑 `.env` 文件：
+
+```env
+ADMIN_USERNAME=admin
+ADMIN_PASSWORD=your-secure-password
+ADMIN_EMAIL=admin@yourdomain.com
+```
+
+删除数据库后重新启动，将使用新的管理员信息。
+
+## 📊 开发模式
+
+如果您想进行开发或调试：
+
+```bash
+# 开发模式（支持热重载）
+npm run dev
+```
+
+特点：
+- 服务器自动重启（nodemon）
+- 前端热重载（Vite HMR）
+- 自动打开浏览器
+
+## 🔍 检查安装
+
+### 验证 Node.js
+```bash
+node --version
+# 应该 >= 16.0.0
+```
+
+### 验证 npm
+```bash
+npm --version
+# 应该 >= 7.0.0
+```
+
+### 验证 MongoDB
+```bash
+mongod --version
+# 应该 >= 4.4
+```
+
+## 📞 获取帮助
+
+如果遇到其他问题：
+
+1. 查看 [INSTALLATION.md](./INSTALLATION.md) - 详细安装指南
+2. 查看 [README.md](./README.md) - 完整文档
+3. 访问 [GitHub Issues](https://github.com/shijinghao/collabdocchat/issues)
+4. 提交新的 Issue 描述您的问题
+
+## 💡 最佳实践
+
+1. **定期更新**
+   ```bash
+   npm update collabdocchat
+   ```
+
+2. **备份数据**
+   ```bash
+   mongodump --db collabdocchat --out ./backup
+   ```
+
+3. **使用 PM2 管理进程**（生产环境）
+   ```bash
+   npm install -g pm2
+   pm2 start server/index.js --name collabdocchat
+   pm2 startup
+   pm2 save
+   ```
+
+4. **配置反向代理**（生产环境）
+   使用 Nginx 或 Apache 作为反向代理
+
+5. **启用 HTTPS**（生产环境）
+   使用 Let's Encrypt 获取免费 SSL 证书
+
+## 🎉 开始使用
+
+现在您可以：
+
+- ✅ 创建新文档
+- ✅ 邀请团队成员
+- ✅ 实时协作编辑
+- ✅ 使用聊天功能
+- ✅ 管理任务
+- ✅ 上传文件
+
+祝您使用愉快！🚀
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "collabdocchat",
-  "version": "1.2.8",
+  "version": "1.2.9",
   "description": "开源的实时协作文档聊天平台 - 集成任务管理、多人文档编辑、智能点名功能",
   "main": "./server/index.js",
   "type": "module",
@@ -22,7 +22,8 @@
     "install-and-start.sh",
     "QUICK_START.md",
     "INSTALLATION.md",
-    "CONTRIBUTING.md"
+    "CONTRIBUTING.md",
+    "USAGE.md"
   ],
   "keywords": [
     "collaboration",

package/INSTALLATION.md

@@ -1,345 +0,0 @@
-# CollabDocChat 安装指南
-
-## 📦 安装方式
-
-### 方式一：本地安装（推荐）
-
-这是最简单且最可靠的安装方式：
-
-```bash
-# 1. 创建项目目录
-mkdir my-collab-project
-cd my-collab-project
-
-# 2. 初始化 npm 项目
-npm init -y
-
-# 3. 安装 CollabDocChat
-npm install collabdocchat
-
-# 4. 进入安装目录
-cd node_modules/collabdocchat
-
-# 5. 启动应用
-npm start
-```
-
-### 方式二：克隆仓库
-
-适合开发者和需要自定义的用户：
-
-```bash
-# 1. 克隆项目
-git clone https://github.com/shijinghao/collabdocchat.git
-cd collabdocchat
-
-# 2. 安装依赖
-npm install
-
-# 3. 启动应用
-npm start
-```
-
-### 方式三：使用安装脚本
-
-#### Windows 用户
-
-1. 下载 `install-and-start.bat`
-2. 双击运行或在命令行中执行：
-```cmd
-install-and-start.bat
-```
-
-#### Linux/Mac 用户
-
-1. 下载 `install-and-start.sh`
-2. 添加执行权限并运行：
-```bash
-chmod +x install-and-start.sh
-./install-and-start.sh
-```
-
-## 🔧 环境要求
-
-### 必需软件
-
-1. **Node.js** (>= 16.0.0)
-   - 下载地址: https://nodejs.org/
-   - 验证安装: `node --version`
-
-2. **npm** (>= 7.0.0)
-   - 通常随 Node.js 一起安装
-   - 验证安装: `npm --version`
-
-3. **MongoDB** (>= 4.4)
-   - 下载地址: https://www.mongodb.com/try/download/community
-   - 验证安装: `mongod --version`
-
-### MongoDB 安装指南
-
-#### Windows
-
-1. 下载 MongoDB Community Server
-2. 运行安装程序，选择"Complete"安装
-3. 安装 MongoDB Compass (可选的图形界面)
-4. 启动 MongoDB 服务：
-```cmd
-net start MongoDB
-```
-
-#### Mac (使用 Homebrew)
-
-```bash
-# 安装 MongoDB
-brew tap mongodb/brew
-brew install mongodb-community
-
-# 启动 MongoDB
-brew services start mongodb-community
-```
-
-#### Linux (Ubuntu/Debian)
-
-```bash
-# 导入公钥
-wget -qO - https://www.mongodb.org/static/pgp/server-6.0.asc | sudo apt-key add -
-
-# 添加源
-echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/6.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-6.0.list
-
-# 安装
-sudo apt-get update
-sudo apt-get install -y mongodb-org
-
-# 启动服务
-sudo systemctl start mongod
-sudo systemctl enable mongod
-```
-
-## ⚙️ 配置
-
-### 首次运行
-
-首次运行时，应用会自动创建配置文件。您也可以手动创建 `.env` 文件：
-
-```env
-# 服务器配置
-PORT=3000
-NODE_ENV=development
-
-# MongoDB 配置
-MONGODB_URI=mongodb://localhost:27017/collabdocchat
-
-# JWT 配置
-JWT_SECRET=your-secret-key-change-this-in-production
-JWT_EXPIRES_IN=7d
-
-# 管理员账号（首次启动时创建）
-ADMIN_USERNAME=admin
-ADMIN_PASSWORD=admin123
-ADMIN_EMAIL=admin@example.com
-```
-
-### 配置说明
-
-- **PORT**: 服务器端口，默认 3000
-- **MONGODB_URI**: MongoDB 连接字符串
-- **JWT_SECRET**: JWT 密钥，生产环境请务必修改
-- **JWT_EXPIRES_IN**: Token 过期时间
-- **ADMIN_USERNAME/PASSWORD**: 默认管理员账号
-
-## 🚀 启动应用
-
-### 开发模式
-
-```bash
-npm run dev
-```
-
-特点：
-- 自动重启服务器
-- 热重载前端
-- 自动打开浏览器
-
-### 生产模式
-
-```bash
-npm start
-```
-
-### 快速启动
-
-```bash
-npm run quick-start
-```
-
-自动配置并启动应用。
-
-## 🔍 验证安装
-
-### 1. 检查服务器
-
-访问: http://localhost:3000
-
-应该看到登录页面。
-
-### 2. 检查客户端
-
-访问: http://localhost:5173
-
-应该看到应用界面。
-
-### 3. 登录测试
-
-使用默认管理员账号登录：
-- 用户名: `admin`
-- 密码: `admin123`
-
-## ❌ 常见问题
-
-### 问题 1: MongoDB 连接失败
-
-**错误信息**: `MongoNetworkError: connect ECONNREFUSED`
-
-**解决方案**:
-1. 确认 MongoDB 服务已启动
-2. 检查 `.env` 中的 `MONGODB_URI` 配置
-3. 验证 MongoDB 端口 (默认 27017)
-
-```bash
-# Windows
-net start MongoDB
-
-# Mac
-brew services start mongodb-community
-
-# Linux
-sudo systemctl start mongod
-```
-
-### 问题 2: 端口被占用
-
-**错误信息**: `Error: listen EADDRINUSE: address already in use :::3000`
-
-**解决方案**:
-1. 更改 `.env` 中的 `PORT` 配置
-2. 或者停止占用端口的进程
-
-```bash
-# Windows - 查找并结束进程
-netstat -ano | findstr :3000
-taskkill /PID <进程ID> /F
-
-# Mac/Linux
-lsof -ti:3000 | xargs kill -9
-```
-
-### 问题 3: npm 依赖安装失败
-
-**解决方案**:
-```bash
-# 清除缓存
-npm cache clean --force
-
-# 删除 node_modules
-rm -rf node_modules package-lock.json
-
-# 重新安装
-npm install
-```
-
-### 问题 4: Node.js 版本过低
-
-**错误信息**: `Error: The engine "node" is incompatible`
-
-**解决方案**:
-升级 Node.js 到 16.0.0 或更高版本。
-
-## 🛑 停止应用
-
-### 方法一：使用脚本
-
-```bash
-npm run stop
-```
-
-### 方法二：手动停止
-
-在运行应用的终端按 `Ctrl + C`
-
-### 方法三：结束进程
-
-```bash
-# Windows
-taskkill /F /IM node.exe
-
-# Mac/Linux
-pkill -f node
-```
-
-## 📊 性能优化
-
-### 生产环境建议
-
-1. **使用 PM2 管理进程**:
-```bash
-npm install -g pm2
-pm2 start server/index.js --name collabdocchat
-pm2 startup
-pm2 save
-```
-
-2. **配置反向代理** (Nginx):
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_http_version 1.1;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection 'upgrade';
-        proxy_set_header Host $host;
-        proxy_cache_bypass $http_upgrade;
-    }
-}
-```
-
-3. **启用 MongoDB 认证**:
-```javascript
-// .env
-MONGODB_URI=mongodb://username:password@localhost:27017/collabdocchat?authSource=admin
-```
-
-## 🔐 安全建议
-
-1. **修改默认管理员密码**
-2. **使用强 JWT 密钥**
-3. **启用 HTTPS**
-4. **配置防火墙规则**
-5. **定期更新依赖包**
-
-```bash
-npm audit
-npm audit fix
-```
-
-## 📞 获取帮助
-
-如果遇到问题：
-
-1. 查看 [GitHub Issues](https://github.com/shijinghao/collabdocchat/issues)
-2. 阅读 [完整文档](https://github.com/shijinghao/collabdocchat#readme)
-3. 提交新的 Issue
-
-## 🎉 安装成功！
-
-现在您可以：
-- 创建文档并邀请团队成员协作
-- 使用实时聊天功能
-- 管理任务和项目
-- 探索更多功能
-
-祝您使用愉快！🚀
-