NodeLoc 社区发卡系统

一个现代化的卡密发卡系统，基于 Go + Vue 3 开发，支持 NodeLoc 社区 OAuth 登录和支付集成。

功能特性 • 快速开始 • 部署指南 • 开发文档

📋 目录

功能特性
技术栈
系统架构
快速开始
部署指南
配置说明
API 文档
开发文档
常见问题
贡献指南
许可证

✨ 功能特性

🛒 商城功能

✅ 商品分类管理
✅ 商品展示与购买
✅ 库存自动管理
✅ 订单查询与详情
✅ 卡密自动发放
✅ 图片上传（商品图片、分类图标）

👤 用户系统

✅ NodeLoc OAuth 一键登录
✅ 用户个人中心
✅ 订单历史记录
✅ 用户权限管理
✅ 用户黑名单功能

💳 支付系统

✅ NodeLoc Payment 支付集成
✅ 免费模式支持（无需配置支付）
✅ 支付回调处理
✅ 订单状态自动更新

🔧 管理后台

✅ 仪表盘（数据统计）
✅ 商品管理（CRUD）
✅ 分类管理
✅ 卡密管理（批量导入）
✅ 订单管理
✅ 用户管理
✅ 系统设置

🎨 用户界面

✅ 响应式设计（支持移动端）
✅ 现代化 UI（Tailwind CSS）
✅ 深色/浅色主题（可扩展）
✅ 流畅的交互体验
✅ 加载状态提示
✅ 错误提示处理

🛠 技术栈

后端

语言: Go 1.21+
框架: Gin Web Framework
ORM: GORM
数据库: MySQL 8.0+
认证: OAuth 2.0
其他:
- godotenv - 环境变量管理
- golang.org/x/crypto - 密码加密

前端

框架: Vue 3.4+
路由: Vue Router 4
状态管理: Pinia
HTTP 客户端: Axios
UI 框架: Tailwind CSS
图标: Lucide Vue Next
构建工具: Vite

部署

容器化: Docker & Docker Compose
Web 服务器: Nginx (前端)
反向代理: 支持任意反向代理

🏗 系统架构

┌─────────────────────────────────────────────────────────┐
│                      用户浏览器                            │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                  Nginx (前端静态文件)                      │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│              Go Gin Backend (API 服务)                    │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │  Handler │  │ Service  │  │  Model   │             │
│  └──────────┘  └──────────┘  └──────────┘             │
│       │              │              │                   │
│       └──────────────┼──────────────┘                   │
│                      │                                   │
└──────────────────────┼───────────────────────────────────┘
                       │
           ┌───────────┼───────────┐
           ▼           ▼           ▼
    ┌──────────┐ ┌──────────┐ ┌──────────┐
    │  MySQL   │ │ NodeLoc  │ │ Payment  │
    │ Database │ │  OAuth   │ │   API    │
    └──────────┘ └──────────┘ └──────────┘

🚀 快速开始

前置要求

Go 1.21 或更高版本
Node.js 18 或更高版本
MySQL 8.0 或更高版本
Docker & Docker Compose（可选，推荐用于生产环境）

本地开发

1. 克隆项目

git clone https://github.com/nodeloc/store.git
cd nl-faka

2. 配置环境变量

cp env.example .env

编辑 .env 文件，配置必要的参数（详见配置说明）

3. 启动数据库

# 使用 Docker 快速启动 MySQL
docker run -d \
  --name faka-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=faka \
  -p 3306:3306 \
  mysql:8.0

4. 启动后端

# 安装依赖
go mod download

# 运行后端服务
go run main.go

后端将在 http://localhost:8080 启动

5. 启动前端

cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

前端将在 http://localhost:5173 启动

🐳 部署指南

方式一：一键部署脚本（最简单）⭐

# 克隆项目
git clone https://github.com/nodeloc/store.git
cd store

# 运行一键部署脚本
./quick-start.sh

脚本会自动：

检查 Docker 环境
创建配置文件
选择部署方式（源码构建 / Docker Hub 镜像）
启动所有服务

方式二：使用 Docker Compose（推荐）

1. 准备环境

# 克隆项目
git clone https://github.com/nodeloc/store.git
cd store

# 配置环境变量
cp .env.production .env
# 编辑 .env 文件，配置必要参数

2. 启动服务

选项 A：使用 Docker Hub 镜像（快速）

# 拉取并启动
docker-compose -f docker-compose.prod.yml up -d

# 查看日志
docker-compose logs -f

选项 B：从源码构建

# 构建并启动所有服务（包含 MySQL）
docker-compose up -d

# 查看日志
docker-compose logs -f

3. 停止服务

docker-compose down

服务将在配置的端口（默认 3000）上启动。

方式三：使用 Docker Hub 镜像快速部署

如果你只想快速体验，可以直接拉取预构建的镜像：

# 创建 docker-compose.yml 和 .env 文件（见下方）
docker-compose up -d

详细说明请查看 docker-deploy.md

3. 配置反向代理（可选）

如果需要通过域名访问，可以配置 Nginx 反向代理：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

手动部署

后端部署

# 构建
go build -o faka-server main.go

# 运行
./faka-server

前端部署

cd frontend

# 构建
npm run build

# dist 目录下的文件部署到 Web 服务器

⚙️ 配置说明

数据库配置

使用 Docker Compose 部署（推荐）

Docker Compose 会自动启动 MySQL，只需配置：

# MySQL root 密码（必改！）
DB_ROOT_PASSWORD=your_strong_root_password

# 应用数据库配置
DB_NAME=faka
DB_USER=faka
DB_PASSWORD=your_strong_db_password
DB_PORT=3306

使用外部 MySQL

DB_HOST=your-mysql-host.com     # MySQL 主机地址
DB_PORT=3306                     # MySQL 端口
DB_USER=faka_user                # 数据库用户名
DB_PASSWORD=your_password        # 数据库密码
DB_NAME=faka                     # 数据库名称

服务器配置

PORT=3000                        # 前端访问端口
SERVER_PORT=8080                 # 后端 API 端口（可选）
GIN_MODE=release                 # Gin 运行模式：debug/release
SESSION_SECRET=random_string     # Session 密钥（首次运行自动生成）

NodeLoc OAuth 配置（必填）

访问 NodeLoc OAuth 应用管理
创建新应用，获取凭证

NODELOC_URL=https://www.nodeloc.com
NODELOC_CLIENT_ID=your-client-id
NODELOC_CLIENT_SECRET=your-client-secret
NODELOC_REDIRECT_URI=https://your-domain.com/auth/callback

NodeLoc Payment 配置（可选）

如果不配置支付，系统将以免费模式运行（用户下单直接获得卡密）。

访问 NodeLoc Payment 应用管理
创建支付应用，获取凭证

PAYMENT_ID=pay_xxxxxxxxxx
PAYMENT_SECRET=your-payment-secret
PAYMENT_CALLBACK_URI=https://your-domain.com/payment/callback

📚 API 文档

公开接口

商品相关

GET    /api/categories           # 获取分类列表
GET    /api/categories/:id       # 获取分类详情
GET    /api/products              # 获取商品列表
GET    /api/products/:id          # 获取商品详情

订单相关

POST   /api/orders                # 创建订单
GET    /api/orders                # 获取我的订单列表
GET    /api/orders/:id            # 获取订单详情

用户相关

GET    /api/profile               # 获取个人信息
PUT    /api/profile               # 更新个人信息

管理员接口

需要管理员权限，路径前缀：/admin

GET    /admin/dashboard           # 仪表盘数据
GET    /admin/users               # 用户列表
PUT    /admin/users/:id           # 更新用户
DELETE /admin/users/:id           # 删除用户

GET    /admin/categories          # 分类管理
POST   /admin/categories          # 创建分类
PUT    /admin/categories/:id      # 更新分类
DELETE /admin/categories/:id      # 删除分类

GET    /admin/products            # 商品管理
POST   /admin/products            # 创建商品
PUT    /admin/products/:id        # 更新商品
DELETE /admin/products/:id        # 删除商品

GET    /admin/cards               # 卡密管理
POST   /admin/cards               # 批量导入卡密
DELETE /admin/cards/:id           # 删除卡密

GET    /admin/orders              # 订单管理
PUT    /admin/orders/:id          # 更新订单状态

🔧 开发文档

项目结构

.
├── main.go                 # 程序入口
├── config/                 # 配置管理
│   └── config.go
├── database/               # 数据库连接
│   └── mysql.go
├── models/                 # 数据模型
│   └── models.go
├── handler/                # 请求处理器
│   ├── auth.go
│   ├── payment.go
│   ├── upload.go
│   ├── admin/              # 管理员接口
│   ├── api/                # 公开接口
│   └── public/
├── services/               # 业务逻辑层
│   ├── admin.go
│   ├── cardkey.go
│   ├── category.go
│   ├── order.go
│   ├── payment.go
│   ├── product.go
│   ├── setting.go
│   └── user.go
├── middleware/             # 中间件
│   └── middleware.go
├── oauth/                  # OAuth 客户端
│   └── client.go
├── payment/                # 支付客户端
│   └── client.go
└── frontend/               # 前端项目
    ├── src/
    │   ├── components/     # 组件
    │   ├── views/          # 页面
    │   ├── router/         # 路由
    │   ├── stores/         # 状态管理
    │   ├── utils/          # 工具函数
    │   └── layouts/        # 布局组件
    └── public/

添加新功能

添加数据模型：在 models/models.go 中定义结构体
创建 Service：在 services/ 中实现业务逻辑
创建 Handler：在 handler/ 中实现请求处理
注册路由：在 main.go 中注册路由
前端实现：在 frontend/src/views/ 中创建页面

数据库迁移

系统使用 GORM 自动迁移，修改模型后重启服务即可自动更新表结构。

❓ 常见问题

1. 数据库连接失败

检查 MySQL 服务是否启动
确认 .env 中的数据库配置正确
确保数据库用户有足够的权限

2. OAuth 登录失败

确认 NODELOC_CLIENT_ID 和 NODELOC_CLIENT_SECRET 配置正确
确认 NODELOC_REDIRECT_URI 与 NodeLoc 应用设置一致
检查应用是否已在 NodeLoc 激活

3. 支付回调未收到

确认 PAYMENT_CALLBACK_URI 可从公网访问
检查防火墙和反向代理配置
查看后端日志确认回调请求

4. 前端无法访问后端 API

检查 frontend/src/utils/api.js 中的 API 地址配置
确认后端服务已启动
检查 CORS 配置

5. 如何添加管理员账号

首次启动时，系统会自动创建默认管理员：

用户名：admin
密码：admin123

请立即修改默认密码！

也可以在数据库中将普通用户的 is_admin 字段设置为 1。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

📄 许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

� Docker 相关

构建并推送镜像到 Docker Hub

# 登录 Docker Hub
docker login

# 使用自动化脚本构建并推送
./build-and-push.sh -u yourusername -v v1.0.0

# 或手动构建
docker build -t yourusername/faka-backend:latest .
docker build -t yourusername/faka-frontend:latest ./frontend

# 推送镜像
docker push yourusername/faka-backend:latest
docker push yourusername/faka-frontend:latest

使用自定义镜像

在 .env 文件中设置：

DOCKER_IMAGE_BACKEND=yourusername/faka-backend:latest
DOCKER_IMAGE_FRONTEND=yourusername/faka-frontend:latest

详细说明请查看 docker-deploy.md

🔗 相关链接

📧 联系方式

如有问题或建议，请通过以下方式联系：

提交 Issue: GitHub Issues
NodeLoc 论坛: www.nodeloc.com

⭐ 如果这个项目对你有帮助，请给我们一个 Star！

Made with ❤️ by NodeLoc Community

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
config		config
database		database
docker/mysql		docker/mysql
handler		handler
marketpro		marketpro
middleware		middleware
models		models
oauth		oauth
payment		payment
services		services
.dockerignore		.dockerignore
.env.production		.env.production
.gitignore		.gitignore
BUILD_TROUBLESHOOTING.md		BUILD_TROUBLESHOOTING.md
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
PUBLISH.md		PUBLISH.md
README.md		README.md
build-and-push.sh		build-and-push.sh
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
docker-deploy.md		docker-deploy.md
env.example		env.example
go.mod		go.mod
go.sum		go.sum
main.go		main.go
publish.sh		publish.sh
quick-start.sh		quick-start.sh

Folders and files

Latest commit

History

Repository files navigation

NodeLoc 社区发卡系统

📋 目录

✨ 功能特性

🛒 商城功能

👤 用户系统

💳 支付系统

🔧 管理后台

🎨 用户界面

🛠 技术栈

后端

前端

部署

🏗 系统架构

🚀 快速开始

前置要求

本地开发

1. 克隆项目

2. 配置环境变量

3. 启动数据库

4. 启动后端

5. 启动前端

🐳 部署指南

方式一：一键部署脚本（最简单）⭐

方式二：使用 Docker Compose（推荐）

1. 准备环境

2. 启动服务

3. 停止服务

方式三：使用 Docker Hub 镜像快速部署

3. 配置反向代理（可选）

手动部署

后端部署

前端部署

⚙️ 配置说明

数据库配置

服务器配置

NodeLoc OAuth 配置（必填）

NodeLoc Payment 配置（可选）

📚 API 文档

公开接口

商品相关

订单相关

用户相关

管理员接口

🔧 开发文档

项目结构

添加新功能

数据库迁移

❓ 常见问题

1. 数据库连接失败

2. OAuth 登录失败

3. 支付回调未收到

4. 前端无法访问后端 API

5. 如何添加管理员账号

🤝 贡献指南

📄 许可证

� Docker 相关

构建并推送镜像到 Docker Hub

使用自定义镜像

🔗 相关链接

📧 联系方式

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages