# X-WS-Server

**Repository Path**: itwxb/X-WS-Server

## Basic Information

- **Project Name**: X-WS-Server
- **Description**: 基于 Node.js 和 Redis 构建的生产级 WebSocket 服务方案
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-31
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🚀 X-WS-Server
### 高性能分布式 WebSocket 生产级服务方案
### Enterprise-Grade Distributed WebSocket Server for Production

[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
[![Node.js](https://img.shields.io/badge/Node.js-v20.19.6-green.svg)](https://nodejs.org/)
[![Redis](https://img.shields.io/badge/Redis-Pub%2FSub-red.svg)](https://redis.io/)

[简体中文](#chinese) | [English](#english)

</div>

---

<a id="chinese"></a>
## 🇨🇳 简体中文版

> ⚠️ **部署注意**: 本项目专为**宝塔面板**环境开发与优化，目前仅在宝塔面板（Node.js 项目管理器）下完成生产测试，暂未在其他服务器环境进行压力测试。

### 📖 简介
**X-WS-Server** 是一款基于 **Node.js** 和 **Redis** 构建的生产级 WebSocket 服务方案。专为高并发、高可靠性和横向扩展能力而设计。该项目严格遵循互联网大厂的高可用交付标准，完美适配微信小程序等实时应用场景。

### ✨ 核心特性
- **🛡️ 企业级可靠性**：基于 `msgId` 溯源的严格 ACK 协议，确保弱网环境下消息零丢失。
- **⚡ 分布式扩展**：无状态架构，通过 Redis 实现跨服务器集群的消息广播，支持无限横向扩展。
- **📊 全方位监控**：内置 `/monitor` 可视化大屏及 Prometheus `/metrics` 指标接口。
- **🔄 工业级运维**：集成 PM2 实现无损发布、进程守护及自动扩缩容。

### 🚀 快速上手
> **💡 到手即用 (Zero-Config)**: 本项目内置了完善的默认配置。如果你本地已启动 Redis (127.0.0.1:6379)，**无需任何配置**，直接执行 `npm run dev` 即可运行！
> 
> **推荐环境**: Node.js `v20.19.6` (LTS)

```bash
# 1. 安装依赖
git clone https://github.com/yourusername/ws-backend-service.git
npm install
```
# 2. 启动服务 (默认端口 8080)
npm run dev
```

### ⚙️ 环境配置 (可选)
虽然可以“到手即用”，但在生产环境下，你可能需要修改端口或 Redis 密码：
```bash
# 1. 配置环境变量
cp .env.example .env

# 2. 生产环境部署 (推荐)
npm run prestart    # 环境预检
npm run pm2:start   # 启动集群模式
```

### � 服务端点
| 功能 | 路径 | 描述 |
|----------|-------------|-------------|
| **WebSocket** | `ws://localhost:8080/ws` | WebSocket 连接地址 |
| **监控面板** | `http://localhost:8080/monitor` | **可视化状态大屏** |
| **监控指标** | `http://localhost:8080/metrics` | Prometheus 指标接口 |
| **健康检查** | `http://localhost:8080/health` | 服务状态检查 |

### �️ 调试与测试
为了方便快速验证服务状态，你可以使用以下工具：
- **内置监控页**: `http://localhost:8080/monitor` (生产环境替换为你的域名) —— **推荐：可直接看到实时消息流**。
- **在线测试工具**: [WebSocket在线测试](https://wstool.js.org/) 或 [Hoppscotch](https://hoppscotch.io/realtime/websocket)
    - **连接地址示例**: `wss://ws.xingfulianxian.xyz/ws`
    - **测试步骤**: 连接成功后，发送 `{"type":"LOGIN","payload":{"userId":"test_user"}}` 即可看到登录成功的反馈。

### � 系统架构
```mermaid
graph TD
    客户端A[客户端 A] <-->|WS| 服务端1[Node.js 节点 1]
    客户端B[客户端 B] <-->|WS| 服务端2[Node.js 节点 2]
    服务端1 <-->|Pub/Sub| Redis[(Redis 集群)]
    服务端2 <-->|Pub/Sub| Redis
```

### 📚 相关文档
- [前端接入指南](docs/FRONTEND_GUIDE.md)
- [宝塔部署手册](docs/DEPLOY_BAOTA.md)
- [项目维护手册](docs/MAINTAINING.md)

### 📈 版本迭代
| 版本 | 日期 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| **v1.0.0** | 2026-01-31 | `Release` | **生产级初始版本发布**：含分布式架构、实时监控、大厂 ACK 协议及全套部署文档。 |

---

<a id="english"></a>
## 🇺🇸 English Version

> ⚠️ **Deployment Note**: This project is specifically developed and optimized for **Baota Panel** (Pagoda). Production testing has only been conducted within the Baota environment. Other environments have not been fully tested.

### 📖 Introduction
**X-WS-Server** is a production-ready WebSocket server solution built with **Node.js** and **Redis**. It is designed for high-concurrency, reliability, and horizontal scalability. Originally architected for WeChat Mini Programs, it strictly adheres to enterprise high-availability standards.

### ✨ Key Features
- **🛡️ Enterprise Reliability**: Robust `ACK` protocol with `msgId` tracing to ensure zero message loss.
- **⚡ Distributed & Scalable**: Stateless architecture for horizontal scaling via Redis Pub/Sub.
- **📊 Observability**: Built-in `/monitor` page and Prometheus `/metrics` endpoint.
- **🔄 Graceful Management**: Integrated with PM2 for zero-downtime deployment.

### 🚀 Quick Start
> **💡 Out-of-the-Box (Zero-Config)**: This project comes with sensible defaults. If you have Redis running locally (127.0.0.1:6379), you can **run it immediately** without any configuration!
> 
> **Recommended Environment**: Node.js `v20.19.6` (LTS)

```bash
# 1. Install
git clone https://github.com/yourusername/ws-backend-service.git
npm install

# 2. Run (Default port 8080)
npm run dev
```

### ⚙️ Configuration (Optional)
While it works out-of-the-box, you may want to customize settings for production:
```bash
# 1. Setup Environment
cp .env.example .env

# 2. Production Deployment
npm run prestart    # Pre-flight Check
npm run pm2:start   # Start with PM2 Cluster
```

### 🔗 Endpoints
| Feature | Path | Description |
|----------|-------------|-------------|
| **WebSocket** | `ws://localhost:8080/ws` | Connection Endpoint |
| **Dashboard** | `http://localhost:8080/monitor` | **Visual Status Monitor** |
| **Metrics** | `http://localhost:8080/metrics` | Prometheus Metrics |
| **Health** | `http://localhost:8080/health` | Service Health Check |

### 🛠️ Testing & Debugging
For quick verification of the service status:
- **Built-in Monitor**: `http://localhost:8080/monitor` (Replace with your domain in production) — **Recommended: Real-time message streaming**.
- **Online Testers**: [WebSocket Online Test](https://wstool.js.org/) or [Hoppscotch](https://hoppscotch.io/realtime/websocket)
    - **Endpoint Example**: `wss://your-domain.com/ws`
    - **Quick Start**: Once connected, send `{"type":"LOGIN","payload":{"userId":"test_user"}}` to verify authentication.

### 📐 Architecture
```mermaid
graph TD
    Client_A[Client A] <-->|WS| Server_1[Node.js Server 1]
    Client_B[Client B] <-->|WS| Server_2[Node.js Server 2]
    Server_1 <-->|Pub/Sub| Redis[(Redis)]
    Server_2 <-->|Pub/Sub| Redis
```

### 📚 Resources
- [Frontend Guide](docs/FRONTEND_GUIDE.md)
- [Deployment Guide](docs/DEPLOY_BAOTA.md)
- [Maintenance Manual](docs/MAINTAINING.md)

---

## 📄 License / 授权协议
Licensed under **ISC License**.