# 卡密系统部署指南

> 版本：v1.0
> 日期：2026-02-03

---

## 一、环境要求

| 项目 | 要求 |
|-----|------|
| PHP版本 | 7.4+ |
| 数据库 | SQLite 3 |
| Web服务器 | Nginx / Apache |
| 扩展 | curl, json, pdo_sqlite |

---

## 二、部署步骤

### 1. 上传文件

将所有文件上传到服务器，包括：
- `api.php` - API接口入口
- `config.php` - 配置文件
- `database.php` - 数据库操作
- `functions.php` - 公共函数
- `kamika.db` - SQLite数据库文件

### 2. 配置API Key

编辑 `config.php`，设置API Key：

```php
// 添加自定义API Key
define('API_KEY', 'your-secure-api-key-here');
```

建议使用随机生成的32位字符串作为API Key。

### 3. 配置数据库

SQLite数据库 `kamika.db` 已包含所有表结构，无需额外配置。

如需迁移到MySQL，请参考数据库脚本。

### 4. 设置权限

确保以下文件可写：
- `kamika.db` - 数据库文件
- `error.log` - 错误日志文件

```bash
chmod 666 kamika.db
chmod 666 error.log
```

### 5. 配置Web服务器

#### Nginx配置示例：

```nginx
server {
    listen 80;
    server_name your-domain.com;
    root /path/to/your/project;
    index index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}
```

#### Apache配置示例：

确保 `.htaccess` 文件包含以下内容：

```apache
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ index.php [QSA,L]
```

---

## 三、API对接

### 1. 前端对接

在你的小程序/H5页面中引入示例代码：

```html
<script src="card-system-api.js"></script>
<script>
const api = new CardSystemAPI();

// 激活卡密
async function activate() {
    const result = await api.activate('KMxxx', deviceId);
    if (result.success) {
        // 激活成功
        showContent();
    }
}
</script>
```

### 2. 后端对接

使用Python示例代码：

```python
from card_system_api import CardSystemAPI

api = CardSystemAPI(API_URL, API_KEY)
result = api.verify(card_key)
if result['success'] and result['data']['valid']:
    # 订阅有效
    pass
```

---

## 四、测试验证

### 1. API健康检查

```bash
curl -X POST https://your-domain.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"action": "verify", "card_key": "KM_TEST"}'
```

### 2. 预期响应

```json
{
    "success": false,
    "message": "卡密不存在",
    "error_code": 1001
}
```

### 3. 常见问题

#### Q1: 返回"API Key无效"

检查：
- 请求头中是否包含 `Authorization: Bearer xxx`
- API Key是否正确
- API Key是否有权限

#### Q2: 返回"请求参数错误"

检查：
- 是否包含 `action` 参数
- JSON格式是否正确
- 必填参数是否完整

#### Q3: 数据库连接失败

检查：
- `kamika.db` 文件是否存在
- 文件权限是否正确
- PHP扩展是否启用

---

## 五、安全建议

1. **启用HTTPS**
2. **定期更换API Key**
3. **限制API调用频率**
4. **记录访问日志**
5. **定期备份数据库**

---

## 六、常见错误码

| 错误码 | 说明 | 解决方案 |
|-------|------|---------|
| 1001 | 卡密不存在 | 检查卡密是否正确 |
| 1002 | 卡密已禁用 | 联系管理员 |
| 1003 | 卡密已过期 | 续费卡密 |
| 1004 | 设备数已达上限 | 解绑其他设备 |
| 3001 | API Key无效 | 检查API Key配置 |

---

## 七、技术支持

如有问题，请联系：
- V：leyilee028
- 小红书/公众号/抖音：@乐意梨      视频号：@宅书房的乐意梨 

---

*文档最后更新时间：2026-02-03*
