“拓学无阻积分互助”平台使用与部署文档

介绍

拓学无阻积分互助 是一个基于 Vue 3 和 Vite 构建的前端，以及使用 Node.js 和 Yarn 作为后端的 Web 应用。兼容多种数据库：兼容sequelize的数据库均可，也支持 VercelSQL等SaaS架构数据库（所有支持的数据库详见 server/src/adapter/*）。

使用已部署的测试环境

访问： http://jtex.jiecs.top （注意测试环境不支持 HTTPS）

测试用户：
用户名：test1
密码：12345678
管理用户：
用户名：0
密码：12345678

Docker Compose自动容器化部署

先决条件：

克隆存储库:

1
2
3
4
5
6
7
8
9
10
git clone <https://github.com/jiesou/JTExchange.git>
cd JTExchange
````
### **运行 Compose 容器组:**

（在项目根目录执行）  
docker compose up -d

Docker Compose将完成依赖环境配置，完成后通过 docker compose logs 可查看运行日志。出现下列字样时即表示已成功部署：

jtexchange-server-1 | Server listening on port 3000
jtexchange-server-1 | Table Users synced.
jtexchange-server-1 | Table Transactions synced.
jtexchange-server-1 | Table Posts synced.

1
2
3
4
5
6
7

可在 <http://127.0.0.1:8080> 访问到

### **修改配置文件：**

重命名server/.env.example为server/.env文件，并根据需要修改其中内容：

SYSTEM_KEY=abcdef
PASSWORD_SALT=abcdef
POSTGRES_URL=postgres://postgres:123456@127.0.0.1:5432/base（会被Docker Compose覆盖）
OPENAI_API_KEY=abcdef OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

## **手动部署**

### **先决条件**

在手动部署“拓学无阻”平台之前，需要确保系统上已安装以下运行环境：

- [Node.js](https://nodejs.org/)
- [Yarn](https://yarnpkg.com/)
- PostgreSQL（或外部/兼容sequelize的数据库均可，所有支持的数据库详见 server/src/adapter/\*）
- 良好的网络连接

## **安装与部署**

### **数据库设置 (PostgreSQL为例)**

- 安装 PostgreSQL。
- 创建一个新的数据库：

```bash
createdb tx_db

后端安装与配置 (Node.js + Yarn)

  • 克隆存储库：
1
2
git clone https://github.com/jiesou/JTExchange.git
cd JTExchange
  • 安装后端依赖项：
1
yarn install
  • 配置服务端：

重命名 server/.env.example 为 server/.env 文件，并根据需要修改其中内容：

1
2
3
4
SYSTEM_KEY=abcdef  
PASSWORD_SALT=abcdef  
POSTGRES_URL=postgres://postgres:123456@127.0.0.1:5432/base（会被Docker Compose覆盖）  
OPENAI_API_KEY=abcdef OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

前端安装与配置 (Vue 3 + Vite)

  • 进入 client 目录：

（在项目根目录执行）

1
cd client
  • 安装前端依赖项：
1
yarn install

启动

  • 确保 PostgreSQL 服务已启动。
  • 启动后端服务器：

（在项目根目录执行）

1
2
cd server  
yarn start
  • 启动前端服务器：

（在项目根目录执行）

1
2
cd client  
yarn dev
  • 后端会监听本地3000端口，或可通过环境变量PORT端口来修改其监听的端口
  • 前端vite默认提示所监听的端口，并将http://localhost:3000 反向代理到前端的 /api 路径，所以使用时只需要开放前端端口即可。实际上，vite build可直接将前端程序构建为纯静态产物，可动静态分离。

账号管理

创建账户

  • 点击页面上方的登录。
  • 点击“注册”按钮。
  • 输入相关信息，完成注册。

账户管理

  • **注意：**ID为0的用户是管理用户（即老师身份），必须创建，可以发起金额为负值的交易，自身余额也允许为负值。
  • **注意：**SYSTEM_KEY环境变量所指向的密钥拥有系统管理用户的访问权限，能够通过/api/sudo/*API执行特殊权限操作，例：
1
2
3
4
5
curl --location '<http://127.0.0.1:3000/api/sudo/new_system_transaction>' \\
\--header 'Content-Type: application/x-www-form-urlencoded' \\
\--header 'X-Key: SYSTEM_KEY' \\
\--data-urlencode 'to=TO_ID' \\
\--data-urlencode 'amount=100'

即向TO_ID凭空转账100个代币，交易记录中会显示交易来自用户0

  • 用户可以在个人中心修改密码、更新个人信息等。
  • 仅管理员可管理用户权限和账户状态。

常见问题

无法连接数据库？

  • 确保 PostgreSQL 正在运行，并检查 .env 配置是否正确。

前端或后端无法启动？

  • 确保依赖项已正确安装 (yarn install)。
  • 检查端口是否被占用。
  • 如使用Docker Compose自动部署，可尝试 docker compose build 重新构建应用镜像。

如何部署到生产环境？

  • 推荐使用Docker进行容器化部署，或者使用PM2管理 Node.js 进程。
  • 推荐外部再套一层 Nginx（Docker Compose已经自带一个实现动静态分离的Nginx了）。