# foryourx-qoder

**Repository Path**: lonlier/foryourx-qoder

## Basic Information

- **Project Name**: foryourx-qoder
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智汇桥 - 专家成果与需求转化匹配平台

产学研对接平台，连接创新与产业，推动成果转化。允许用户发布科研成果和技术需求，系统进行智能匹配，管理员后台审核管理。

## 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                      Nginx (:80)                        │
│         静态文件服务 + API 反向代理                        │
├──────────────┬──────────────┬───────────────────────────┤
│  前台 Web    │  管理后台     │      API Server (:3000)   │
│  React SPA   │  React SPA   │   Express + Sequelize     │
│  /           │  /admin      │   /api/*                  │
└──────────────┴──────────────┴─────────┬─────────────────┘
                                        │
                                ┌───────┴───────┐
                                │  MySQL 8.0    │
                                │  (:3306)      │
                                └───────────────┘
```

## 技术栈

| 层级 | 技术 |
|------|------|
| 前端(用户端) | React 18 + TypeScript + Vite + Tailwind CSS + Zustand |
| 前端(管理端) | React 18 + TypeScript + Vite + Tailwind CSS + Recharts |
| 后端 | Node.js + Express + TypeScript + Sequelize ORM |
| 数据库 | MySQL 8.0 |
| 部署 | Docker + Docker Compose + Nginx |
| 认证 | JWT (accessToken + refreshToken) |

## 项目结构

```
expert-match-platform/
├── packages/
│   ├── shared/          # 共享类型定义和常量
│   ├── server/          # 后端 API 服务
│   ├── web/             # 前台用户界面
│   └── admin/           # 后台管理界面
├── nginx/               # Nginx 配置
├── docker-compose.yml   # 生产环境编排
├── docker-compose.dev.yml # 开发环境(仅MySQL)
├── pnpm-workspace.yaml
└── .env.example
```

## 功能模块

### 前台用户端

- **首页** - 平台介绍、数据统计、热门成果、最新需求
- **成果大厅** - 成果列表浏览、分类筛选、关键词搜索
- **需求大厅** - 需求列表浏览、分类筛选、关键词搜索
- **成果/需求详情** - 完整信息展示、联系方式
- **发布成果/需求** - 表单提交，进入审核流程
- **用户中心** - 个人资料、我的成果/需求、匹配推荐、消息通知
- **登录/注册** - JWT 认证

### 管理后台

- **数据看板** - 统计卡片、状态分布饼图、趋势面积图、分类柱状图
- **成果管理** - 列表、审核(通过/驳回)、推荐、删除
- **需求管理** - 列表、审核(通过/驳回)、推荐、删除
- **匹配管理** - 自动匹配、手动匹配、状态管理
- **用户管理** - 用户列表、启用/禁用、角色变更
- **分类管理** - 成果类型、需求类型、领域分类的增删改
- **系统设置** - 平台基本信息配置

### 匹配引擎

四维加权评分算法 (0-100分):

| 维度 | 权重 | 算法 |
|------|------|------|
| 关键词匹配 | 40% | Jaccard 相似系数 |
| 领域匹配 | 30% | 领域 ID 重叠率 |
| 文本相似度 | 20% | 关键词在文本中的出现频率 |
| 类型兼容 | 10% | 预定义兼容矩阵查表 |

触发时机: 审核通过时自动触发 / 管理员手动触发 / 每日定时批量

### 成果类型

学术论文、发明专利、实用新型、外观设计、软件著作权、技术标准、产品/样品、技术方案、咨询报告、技术服务

### 需求类型

技术需求、人才需求、合作需求、投融资需求

## 本地开发

### 环境要求

- Node.js >= 18
- pnpm >= 8
- Docker & Docker Compose (用于 MySQL)

### 步骤

```bash
# 1. 克隆项目
git clone <repo-url>
cd expert-match-platform

# 2. 安装依赖
pnpm install

# 3. 配置环境变量
cp .env.example .env
# 按需修改 .env 中的数据库密码、JWT 密钥等

# 4. 启动 MySQL
docker-compose -f docker-compose.dev.yml up -d

# 5. 启动后端(自动建表)
pnpm dev:server

# 6. 初始化种子数据(默认分类 + 管理员账号 + 测试数据)
cd packages/server && npx tsx src/seed.ts && cd ../..

# 7. 启动前台
pnpm dev:web      # http://localhost:5173

# 8. 启动管理后台
pnpm dev:admin    # http://localhost:5174
```

### 默认账号

| 角色 | 邮箱 | 密码 |
|------|------|------|
| 管理员 | admin@admin.com | admin123 |
| 测试用户 | expert1@test.com | 123456 |
| 测试用户 | expert2@test.com | 123456 |

## Linux 服务器部署

### 一、环境准备

```bash
# 1. 安装 Docker
curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker && sudo systemctl start docker

# 2. 安装 Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" \
  -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# 3. 安装 Node.js 20 (用于构建前端)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 4. 安装 pnpm
npm install -g pnpm
```

### 二、上传代码

```bash
# 方式一: Git 拉取
cd /opt
git clone <repo-url> expert-match-platform
cd expert-match-platform

# 方式二: 本地打包上传
# 本地执行: tar czf project.tar.gz --exclude=node_modules --exclude=dist .
# 服务器执行:
mkdir -p /opt/expert-match-platform && cd /opt/expert-match-platform
tar xzf /path/to/project.tar.gz
```

### 三、配置环境变量

```bash
cp .env.example .env
vim .env
```

修改以下关键配置:

```ini
NODE_ENV=production

# 务必修改为强密码
DB_PASSWORD=YourStrongPassword123!

# 务必修改为随机字符串(可用 openssl rand -hex 32 生成)
JWT_SECRET=your-production-jwt-secret-change-this
JWT_REFRESH_SECRET=your-production-refresh-secret-change-this

# 改为你的域名或服务器 IP
WEB_URL=http://your-domain.com
ADMIN_URL=http://your-domain.com/admin
```

同步修改 `docker-compose.yml` 中的对应环境变量(DB_PASSWORD, JWT_SECRET 等)。

### 四、构建前端静态文件

```bash
# 安装依赖
pnpm install

# 构建前台
cd packages/web && npx vite build && cd ../..

# 构建管理后台
cd packages/admin && npx vite build && cd ../..
```

### 五、部署静态文件到 Nginx 目录

```bash
# 创建静态文件目录
sudo mkdir -p /opt/expert-match-platform/dist/web
sudo mkdir -p /opt/expert-match-platform/dist/admin

# 复制构建产物
cp -r packages/web/dist/* /opt/expert-match-platform/dist/web/
cp -r packages/admin/dist/* /opt/expert-match-platform/dist/admin/
```

### 六、修改 Nginx 配置

编辑 `nginx/default.conf`，将静态文件路径改为容器内挂载路径:

```nginx
# 前台
location / {
    root /usr/share/nginx/html/web;
    index index.html;
    try_files $uri $uri/ /index.html;
}

# 管理后台
location /admin {
    alias /usr/share/nginx/html/admin;
    index index.html;
    try_files $uri $uri/ /admin/index.html;
}
```

### 七、修改 docker-compose.yml

将 nginx 服务的 volumes 改为挂载本地构建目录:

```yaml
nginx:
  image: nginx:alpine
  container_name: expert_match_nginx
  restart: unless-stopped
  ports:
    - "80:80"
  volumes:
    - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    - ./dist/web:/usr/share/nginx/html/web
    - ./dist/admin:/usr/share/nginx/html/admin
  depends_on:
    - server
```

### 八、启动服务

```bash
# 启动所有服务(MySQL + API Server + Nginx)
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f server   # API 日志
docker-compose logs -f mysql    # 数据库日志
docker-compose logs -f nginx    # Nginx 日志
```

### 九、初始化数据

等待 MySQL 完全启动后(约 30 秒):

```bash
# 进入 server 容器执行种子数据
docker-compose exec server node -e "
  require('./dist/seed.js')
" 2>/dev/null

# 或者在宿主机直接运行(需要 Node.js 环境)
cd packages/server && DB_HOST=localhost npx tsx src/seed.ts
```

### 十、验证部署

```bash
# 检查 API 是否正常
curl http://localhost/api/stats/overview

# 检查前台页面
curl -I http://localhost/

# 检查管理后台
curl -I http://localhost/admin
```

浏览器访问:
- 前台: `http://your-server-ip/`
- 管理后台: `http://your-server-ip/admin`

### HTTPS 配置 (推荐)

```bash
# 1. 安装 certbot
sudo apt-get install certbot python3-certbot-nginx

# 2. 申请证书
sudo certbot --nginx -d your-domain.com

# 3. 或手动配置 nginx/default.conf 添加 SSL:
server {
    listen 443 ssl;
    server_name your-domain.com;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    # ... 其余配置不变
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}
```

将证书目录挂载到 nginx 容器:

```yaml
nginx:
  volumes:
    - /etc/letsencrypt:/etc/letsencrypt:ro
```

## 原生部署（不使用 Docker）

如果服务器已有 Nginx 和 MySQL，可以不依赖 Docker，直接用系统原生服务部署。

### 一、环境要求

- Linux (Ubuntu/CentOS/Debian)
- Node.js >= 18
- pnpm >= 8
- MySQL >= 5.7 (推荐 8.0)
- Nginx

```bash
# Ubuntu/Debian 安装示例
sudo apt update
sudo apt install -y nginx mysql-server

# 安装 Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g pnpm
```

### 二、配置 MySQL

```bash
# 登录 MySQL
sudo mysql -u root -p

# 创建数据库和用户
CREATE DATABASE expert_match CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'expert_match'@'localhost' IDENTIFIED BY 'YourStrongPassword123!';
GRANT ALL PRIVILEGES ON expert_match.* TO 'expert_match'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

### 三、上传代码并安装依赖

```bash
cd /opt/expert-match-platform
pnpm install
```

### 四、配置环境变量

```bash
cp .env.example .env
vim .env
```

根据实际情况修改 `.env`：

```ini
NODE_ENV=production
PORT=3000

# 对应上面创建的 MySQL 用户
DB_HOST=localhost
DB_PORT=3306
DB_NAME=expert_match
DB_USER=expert_match
DB_PASSWORD=YourStrongPassword123!

# 生成随机密钥: openssl rand -hex 32
JWT_SECRET=替换为随机字符串
JWT_REFRESH_SECRET=替换为另一个随机字符串
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

UPLOAD_DIR=/opt/expert-match-platform/uploads
MAX_FILE_SIZE=20971520

WEB_URL=http://your-domain.com
ADMIN_URL=http://your-domain.com/admin
```

### 五、构建项目

```bash
# 构建前台
cd /opt/expert-match-platform/packages/web && npx vite build

# 构建管理后台
cd /opt/expert-match-platform/packages/admin && npx vite build

# 创建上传目录
mkdir -p /opt/expert-match-platform/uploads
```

### 六、启动后端 API

推荐使用 pm2 管理 Node.js 进程:

```bash
npm install -g pm2

# 使用 tsx 直接运行 TypeScript（免编译，推荐）
cd /opt/expert-match-platform
pm2 start "npx tsx packages/server/src/server.ts" --name expert-api --cwd /opt/expert-match-platform

# 设置开机自启
pm2 save
pm2 startup
```

验证后端启动:

```bash
curl http://localhost:3000/api/stats/overview
```

### 七、初始化种子数据

```bash
cd /opt/expert-match-platform/packages/server
npx tsx src/seed.ts
```

### 八、配置 Nginx

创建 Nginx 站点配置:

```bash
sudo vim /etc/nginx/sites-available/expert-match
```

写入以下内容（**根据实际端口和路径修改**）:

```nginx
upstream expert_api {
    server 127.0.0.1:3000;    # 后端 API 端口，和 .env 中的 PORT 一致
}

server {
    listen 80;                 # Nginx 监听端口
    server_name your-domain.com;  # 改为你的域名或 IP

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript image/svg+xml;

    # 前台 - 用户端 SPA
    location / {
        root /opt/expert-match-platform/packages/web/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }

    # 管理后台 SPA
    location /admin {
        alias /opt/expert-match-platform/packages/admin/dist;
        index index.html;
        try_files $uri $uri/ /admin/index.html;
    }

    # API 反向代理
    location /api/ {
        proxy_pass http://expert_api/api/;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_connect_timeout 60s;
        proxy_read_timeout 120s;
        client_max_body_size 25m;
    }

    # 上传文件静态访问
    location /uploads/ {
        alias /opt/expert-match-platform/uploads/;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }
}
```

启用站点并重启 Nginx:

```bash
sudo ln -s /etc/nginx/sites-available/expert-match /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default   # 移除默认站点（可选）
sudo nginx -t        # 测试配置是否正确
sudo systemctl reload nginx
```

### 九、HTTPS 配置（推荐）

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
# 自动续期
sudo systemctl enable certbot.timer
```

### 十、验证

```bash
curl -I http://your-domain.com/           # 前台
curl -I http://your-domain.com/admin      # 管理后台
curl http://your-domain.com/api/stats/overview  # API
```

### 原生部署常用运维命令

```bash
# 查看后端状态/日志
pm2 status
pm2 logs expert-api

# 重启后端
pm2 restart expert-api

# 重新构建前端后刷新
cd /opt/expert-match-platform/packages/web && npx vite build
cd /opt/expert-match-platform/packages/admin && npx vite build
# 无需重启 Nginx，静态文件立即生效

# MySQL 备份
mysqldump -u expert_match -p expert_match > backup_$(date +%Y%m%d).sql

# MySQL 恢复
mysql -u expert_match -p expert_match < backup.sql

# 查看 Nginx 日志
sudo tail -f /var/log/nginx/access.log
sudo tail -f /var/log/nginx/error.log
```

---

## 端口修改

系统涉及 3 个可配置端口，按需修改:

### 1. 后端 API 端口（默认 3000）

修改 `.env`:

```ini
PORT=8080    # 改为你想要的端口
```

同步修改 Nginx 配置中的 upstream:

```nginx
upstream expert_api {
    server 127.0.0.1:8080;   # 与 .env 中的 PORT 一致
}
```

Docker 部署时还需修改 `docker-compose.yml`:

```yaml
server:
  ports:
    - "8080:8080"
  environment:
    PORT: 8080
```

修改后重启后端: `pm2 restart expert-api` 或 `docker-compose restart server`

### 2. Nginx 监听端口（默认 80）

修改 Nginx 配置:

```nginx
server {
    listen 9090;    # 改为你想要的端口
    # ...
}
```

Docker 部署时修改 `docker-compose.yml`:

```yaml
nginx:
  ports:
    - "9090:9090"     # 宿主机端口:容器端口
```

同时修改 Nginx 配置文件中的 `listen 9090;`

修改后重新加载: `sudo nginx -s reload` 或 `docker-compose restart nginx`

注意: 修改 Nginx 端口后，`.env` 中的 `WEB_URL` 和 `ADMIN_URL` 也要同步更新:

```ini
WEB_URL=http://your-domain.com:9090
ADMIN_URL=http://your-domain.com:9090/admin
```

### 3. MySQL 端口（默认 3306）

修改 `.env`:

```ini
DB_PORT=3307    # 改为你的 MySQL 端口
```

Docker 部署时修改 `docker-compose.yml`:

```yaml
mysql:
  ports:
    - "3307:3306"    # 宿主机端口:容器端口
```

原生 MySQL 修改 `/etc/mysql/mysql.conf.d/mysqld.cnf`:

```ini
[mysqld]
port = 3307
```

然后 `sudo systemctl restart mysql`

### 4. 开发环境前端端口

前台默认 5173，管理后台默认 5174。修改对应的 `vite.config.ts`:

```typescript
// packages/web/vite.config.ts
server: {
  port: 4000,    // 前台端口
  proxy: {
    '/api': { target: 'http://localhost:8080' },  // 指向后端端口
  },
}

// packages/admin/vite.config.ts
server: {
  port: 4001,    // 管理后台端口
  proxy: {
    '/api': { target: 'http://localhost:8080' },  // 指向后端端口
  },
}
```

### 端口修改速查表

| 组件 | 默认端口 | 配置位置 | 关联修改 |
|------|----------|----------|----------|
| 后端 API | 3000 | `.env` → `PORT` | Nginx upstream, docker-compose |
| Nginx | 80 | `nginx/default.conf` → `listen` | docker-compose ports, `.env` URL |
| MySQL | 3306 | `.env` → `DB_PORT` | docker-compose ports 或 mysqld.cnf |
| 前台(开发) | 5173 | `packages/web/vite.config.ts` | 仅开发环境 |
| 后台(开发) | 5174 | `packages/admin/vite.config.ts` | 仅开发环境 |

---

## 常用运维命令

```bash
# 重启所有服务
docker-compose restart

# 重启单个服务
docker-compose restart server

# 停止所有服务
docker-compose down

# 停止并删除数据卷(危险，会清空数据库)
docker-compose down -v

# 查看实时日志
docker-compose logs -f --tail=100

# 进入 MySQL 命令行
docker-compose exec mysql mysql -u root -p expert_match

# 备份数据库
docker-compose exec mysql mysqldump -u root -p expert_match > backup_$(date +%Y%m%d).sql

# 恢复数据库
docker-compose exec -T mysql mysql -u root -p expert_match < backup.sql

# 更新代码后重新部署
git pull
pnpm install
cd packages/web && npx vite build && cd ../..
cd packages/admin && npx vite build && cd ../..
cp -r packages/web/dist/* dist/web/
cp -r packages/admin/dist/* dist/admin/
docker-compose restart server
```

## 数据库表

| 表名 | 说明 |
|------|------|
| users | 用户(含角色: user/admin/super_admin) |
| categories | 分类(成果类型/需求类型/研究领域) |
| achievements | 成果(含审核状态流转) |
| demands | 需求(含审核状态流转) |
| matches | 匹配记录(自动/手动, 含评分) |
| messages | 消息通知 |
| audit_logs | 审核操作日志 |
| attachments | 附件 |

## API 文档

后端 API 基础路径: `/api`

| 模块 | 路径 | 说明 |
|------|------|------|
| 认证 | `/api/auth/*` | 注册、登录、Token 刷新 |
| 成果 | `/api/achievements/*` | 成果列表、详情、发布 |
| 需求 | `/api/demands/*` | 需求列表、详情、发布 |
| 用户中心 | `/api/user/*` | 个人资料、我的内容、消息 |
| 分类 | `/api/categories` | 获取分类树 |
| 统计 | `/api/stats/*` | 平台统计数据 |
| 文件上传 | `/api/upload` | 附件上传 |
| 后台管理 | `/api/admin/*` | 审核、匹配、用户管理等 |