# 卡密管理系统

**Repository Path**: ike_lin/card-system

## Basic Information

- **Project Name**: 卡密管理系统
- **Description**: 为闲鱼虚拟产品卖家打造的卡密管理系统 | 多用户权限管理 | 分组卡密生成 | 客户提交信息收集 | Docker一键部署 | Flask + SQLite
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 卡密管理系统

## 简介

一个为闲鱼虚拟产品卖家设计的卡密管理系统，支持多用户管理、分组管理、卡密生成、客户提交信息收集等功能。

- **后端**：Python + Flask + Gunicorn
- **数据库**：SQLite
- **前端**：HTML + CSS + JavaScript（原生，无框架依赖）
- **依赖**：Flask、Pillow（验证码生成）

## 功能一览

### 分组管理 + 卡密生成
- 新建分组时填写备注（如 `XHS`），自动生成访问链接 `/submit/XHS`
- 每组最多 100 个卡密，16 位随机码（大写字母+数字，已排除易混淆字符 O/0/I/1/L）
- 支持批量生成、复制单个/全部、下载为 txt 文件、清理未使用的卡密

### 多用户管理
- 首个注册用户自动成为管理员，后续为普通用户
- 注册需用户名、密码、邮箱（必填）+ 手机号（选填）+ 验证码
- 登录需验证码，可勾选「保持登录 30 天」
- 管理员可管理所有数据，普通用户仅管理自己的

### 管理员功能
- **用户管理**：新建用户、删除用户、重置密码、修改邮箱/手机号、启用/禁用、设置/取消管理员
- **系统日志**：记录所有操作（登录、创建分组、生成卡密等）
- **系统设置**：站点标题/Logo、邮箱 SMTP 服务器配置 + 测试邮件发送、**备案信息**

### 普通用户功能
- **个人设置**：自定义头像上传、邮箱修改、手机号修改、密码更改、30天保持登录开关
- **邮件通知**：开启后有新客户提交时自动发邮件提醒

### 客户提交页（公开，无需登录）
- 客户打开链接 → 填卡密 + 视频分享链接 → 提交
- 卡密验证：不存在/不属于此分组/已使用 三种错误提示
- 提交后卡密自动标记为已使用，后台可按卡密搜索查询

### 其他
- **首次使用弹窗**：登录页检测到无用户时弹窗提示「第一个注册的将成为管理员」
- **备案信息**：后台和客户提交页底部均显示

---

## 快速开始（Windows 本地）

### 方式一：使用启动脚本
1. 双击 `setup.bat` 初始化环境（仅首次需要）
2. 双击 `run.bat` 启动系统
3. 浏览器访问 http://127.0.0.1:5000

### 方式二：手动启动
```bash
pip install -r requirements.txt
python app.py
```

---

## 部署文档（Linux / Docker）

### 方式一：Docker 部署（推荐）

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

# 安装 docker-compose 插件
sudo apt-get install -y docker-compose-plugin
```

#### 2. 部署应用
```bash
# 克隆代码
git clone https://gitee.com/ike_lin/card-system.git
cd card-system

# 【重要】修改 docker-compose.yml 中的 SECRET_KEY
# 改成一个随机字符串，例如：SECRET_KEY=your-random-secret-abc123

# 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

# 停止
docker compose down
```

#### 3. 访问
打开浏览器访问 `http://你的服务器IP:5000`

#### 4. 数据备份
```bash
# 备份数据库和头像
cp data/instance/card_system.db /backup/
cp -r data/avatars/ /backup/
```

#### 5. 更新代码
```bash
git pull
docker compose up -d --build
```

---

### 方式二：Linux 直接部署

#### 1. 安装 Python 3.10+
```bash
sudo apt update
sudo apt install -y python3 python3-venv python3-pip
```

#### 2. 克隆代码并启动
```bash
git clone https://gitee.com/ike_lin/card-system.git
cd card-system

# 赋予执行权限并运行（自动创建虚拟环境 + 安装依赖 + Gunicorn 启动）
chmod +x run.sh
./run.sh
```

#### 3. 后台运行（使用 systemd）
```bash
# 创建 systemd 服务
sudo cat > /etc/systemd/system/card-system.service << 'EOF'
[Unit]
Description=Card Key Management System
After=network.target

[Service]
User=www-data
WorkingDirectory=/path/to/card-system
ExecStart=/path/to/card-system/venv/bin/gunicorn --bind 0.0.0.0:5000 --workers 4 --timeout 120 wsgi:app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable card-system
sudo systemctl start card-system

# 查看状态
sudo systemctl status card-system
```

---

### 方式三：Nginx 反向代理 + HTTPS

适用于需要用域名访问的场景。

#### 1. 安装 Nginx
```bash
sudo apt install -y nginx
```

#### 2. 配置反向代理
```bash
sudo cat > /etc/nginx/sites-available/card-system << 'EOF'
server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 16M;

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

    # 静态文件直接由 Nginx 处理（可选，加速访问）
    location /static/ {
        alias /path/to/card-system/static/;
        expires 30d;
    }
}
EOF

sudo ln -s /etc/nginx/sites-available/card-system /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

#### 3. 配置 HTTPS（Let's Encrypt 免费证书）
```bash
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

---

### 环境变量说明

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `SECRET_KEY` | card-system-secret-key-... | Flask 会话密钥，**生产环境必须修改** |
| `HOST` | 127.0.0.1 | 监听地址，Docker 中为 0.0.0.0 |
| `PORT` | 5000 | 监听端口 |
| `FLASK_DEBUG` | 1 | 调试模式，生产环境设为 0 |

### 数据目录

| 路径 | 说明 |
|------|------|
| `instance/card_system.db` | SQLite 数据库 |
| `static/avatars/` | 用户上传的头像 |
| `data/` | Docker 持久化目录（含数据库和头像） |

### 常用运维命令

```bash
# Docker 查看日志
docker compose logs -f

# Docker 重启
docker compose restart

# Docker 进入容器
docker compose exec card-system bash

# systemd 查看日志
sudo journalctl -u card-system -f
```

---

## 使用流程

### 1. 注册账号
- 第一个注册的用户**自动成为管理员**
- 之后注册的用户为普通用户

### 2. 创建分组
- 在「分组管理」页面点击「新建分组」
- 填写分组名称和备注（如 `XHS`）
- 系统自动生成访问链接：`http://你的域名/submit/XHS`
- 备注**仅允许大写字母、数字和连字符**

### 3. 生成卡密
- 进入分组详情页，点击「生成卡密」
- 每次最多生成 100 个，每组最多 100 个
- 卡密为 16 位随机码（大写字母+数字）
- 支持复制单个、复制全部、下载为文件

### 4. 发给客户
- 将访问链接和卡密发给客户
- 客户打开链接，填写卡密和视频分享链接
- 提交后卡密自动标记为「已使用」

### 5. 查看提交记录
- 在「提交记录」页面查看所有客户提交
- 可通过卡密搜索对应的提交记录

---

## 目录结构

```
card_system/
├── app.py              # 主应用（所有路由和业务逻辑）
├── db.py               # 数据库模块
├── utils.py            # 工具函数（卡密生成、验证码、邮件）
├── wsgi.py             # Gunicorn WSGI 入口
├── requirements.txt    # Python 依赖
├── Dockerfile          # Docker 构建文件
├── docker-compose.yml  # Docker Compose 编排
├── .dockerignore       # Docker 构建排除
├── setup.bat           # Windows 环境初始化
├── run.bat             # Windows 启动脚本
├── run.sh              # Linux 启动脚本
├── DEPLOY.md           # 独立部署文档
├── instance/           # 数据库目录（自动创建）
├── static/
│   ├── css/style.css   # 样式
│   ├── js/main.js      # 脚本
│   └── avatars/        # 用户头像（自动创建）
└── templates/          # HTML 模板
```

## 常见问题

**Q: 忘记密码怎么办？**
A: 删除 `instance/card_system.db` 文件后重启，系统会重新初始化（数据会丢失）。或者让管理员在「用户管理」中重置密码。

**Q: 如何修改监听端口？**
A: 设置环境变量 `PORT=8080`（Docker 中修改 docker-compose.yml 的 ports 映射即可）。

**Q: 如何让外网访问？**
A: 设置 `HOST=0.0.0.0`，并在路由器上做端口映射；或使用 Nginx 反向代理（见上方部署文档）。

**Q: Docker 部署后数据会丢失吗？**
A: 不会。docker-compose.yml 已配置数据卷，数据库和头像保存在 `./data/` 目录中，容器删除重建后数据仍在。

**Q: 如何配置邮件通知？**
A: 管理员在「系统设置 → 邮箱服务器」配置 SMTP 信息，普通用户在「个人设置」中勾选「有新提交时邮件通知」。