开发环境搭建

提示

如果你只是想快速体验 CCXC Engine，可以直接参考部署指南。开发环境搭建与部署过程基本相同。

当你需要进行二次开发时，再根据具体需求搭建相应组件的开发环境。

系统要求

操作系统

推荐：Linux（Ubuntu 20.04+、Debian 11+）
兼容：Windows 10/11（完全支持开发）
兼容：macOS（Intel/Apple Silicon）

开发工具

Node.js v22.0.0 或更高版本
.NET 8.0 SDK 或 Visual Studio 2022
Git 用于版本控制

必需中间件

CCXC Engine 依赖以下中间件，此处只列出了我们推荐的最低版本，但是我们仍然推荐你安装最新稳定版本以获得最佳性能和安全性：

数据库

MariaDB 10.11.2 或更高版本
或 MySQL 8.0 或更高版本

缓存与消息队列

Redis 5.0.9 或更高版本

Web 服务器

Nginx 1.17 或更高版本（用于反向代理和静态文件服务）

注意

以上中间件在生产环境部署时同样必需。建议在开发阶段就使用与生产环境一致的版本。

架构概览与端口规划

CCXC Engine 采用微服务架构，由五个核心组件组成，所有服务均要求运行在 HTTPS 环境下。

服务架构图

端口分配表

组件	域名	端口	说明
ccxc-backend	-	52412	主后端服务，通过 Nginx 代理
ccxc-sync-server	-	15562	WebSocket 同步服务，通过 Nginx 代理
MariaDB	-	3306	数据库服务
Redis	-	6379	缓存服务
Nginx (API)	api.ccxc.ikp.yt	22443	API 反向代理
Nginx (静态)	static.ccxc.ikp.yt	22443	静态文件服务
ccxc-admin	admin.ccxc.ikp.yt	5137	管理后台
ccxc-website	www.ccxc.ikp.yt	13880	主站前端
ccxc-puzzle	puzzle.ccxc.ikp.yt	20480	谜题前端

开发域名说明

我们使用 ccxc.ikp.yt 作为开发域名，该域名及其所有子域名（*.ccxc.ikp.yt）已指向 127.0.0.1，可直接用于本地开发。

环境准备

1. 安装 HTTPS 证书工具

由于所有组件都需要 HTTPS 环境，需要安装 mkcert 生成本地开发证书：

Windows (使用 Winget):

powershell

winget install mkcert

Linux (手动安装):

bash

curl -JLO "https://dl.filippo.io/mkcert/latest?for=linux/amd64"
chmod +x mkcert-v*-linux-amd64
sudo mv mkcert-v*-linux-amd64 /usr/local/bin/mkcert

2. 生成开发证书

为 API 和静态文件服务生成 SSL 证书：

bash

# 安装本地 CA
mkcert -install

# 生成证书
mkcert api.ccxc.ikp.yt static.ccxc.ikp.yt

此命令会生成 api.ccxc.ikp.yt+1.pem 和 api.ccxc.ikp.yt+1-key.pem 两个文件，请记录文件位置，稍后配置 Nginx 时需要使用。

前端组件自动证书

三个前端组件（ccxc-admin、ccxc-website、ccxc-puzzle）已内置 mkcert 自动证书生成，无需手动配置。

3. 配置 MariaDB

安装 MariaDB

Ubuntu/Debian:

bash

sudo apt update
sudo apt install mariadb-server
sudo mysql_secure_installation

Windows: 下载并安装 MariaDB for Windows

创建数据库和用户

sql

-- 连接到 MariaDB
mysql -u root -p

-- 创建数据库
CREATE DATABASE ccxc_dev CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户
CREATE USER 'ccxc_user'@'localhost' IDENTIFIED BY 'your_secure_password';

-- 授予权限
GRANT ALL PRIVILEGES ON ccxc_dev.* TO 'ccxc_user'@'localhost';
GRANT SELECT ON information_schema.* TO 'ccxc_user'@'localhost';

-- 刷新权限
FLUSH PRIVILEGES;
EXIT;

重要说明

必须为用户授予 information_schema 的读权限，因为 CCXC Engine 采用 Code First 方式自动管理数据库结构。

4. 配置 Redis

安装 Redis

Ubuntu/Debian:

bash

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

Windows: 下载并安装 Redis Windows Version

启动 Redis

bash

# 默认配置启动
redis-server

# 或使用自定义配置
redis-server /path/to/redis.conf

验证安装

bash

redis-cli ping
# 应返回: PONG

5. 配置 Nginx

安装 Nginx

Ubuntu/Debian:

bash

sudo apt update
sudo apt install nginx

Windows: 下载 Nginx for Windows

配置文件

创建 Nginx 配置文件 /etc/nginx/sites-available/ccxc-dev（Windows 下为 nginx.conf）：

nginx

# WebSocket 连接升级配置
map $http_upgrade $connection_upgrade {
    default upgrade;
    '' close;
}

# 后端服务负载均衡
upstream ccxc_backend {
    server 127.0.0.1:52412;
    keepalive 64;
}

upstream ccxc_sync {
    server 127.0.0.1:15562;
    keepalive 64;
}

# API 服务器配置
server {
    listen 22443 ssl http2;
    listen [::]:22443 ssl http2;
    server_name api.ccxc.ikp.yt;

    # SSL 证书配置（请替换为实际路径）
    ssl_certificate "/path/to/api.ccxc.ikp.yt+1.pem";
    ssl_certificate_key "/path/to/api.ccxc.ikp.yt+1-key.pem";
    
    # SSL 优化配置
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # WebSocket 代理（同步服务）
    location /ws-api {
        proxy_pass http://ccxc_sync;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $http_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;
    }

    # API 代理（主后端）
    location / {
        proxy_pass http://ccxc_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $http_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;
    }
}

# 静态文件服务器配置
server {
    listen 22443 ssl http2;
    listen [::]:22443 ssl http2;
    server_name static.ccxc.ikp.yt;

    # SSL 证书配置
    ssl_certificate "/path/to/api.ccxc.ikp.yt+1.pem";
    ssl_certificate_key "/path/to/api.ccxc.ikp.yt+1-key.pem";
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    # 静态文件根目录
    root "/var/www/static";
    index index.html;

    # CORS 配置
    location / {
        # 处理 OPTIONS 预检请求
        if ($request_method = 'OPTIONS') {
            add_header Access-Control-Allow-Origin *;
            add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
            add_header Access-Control-Allow-Headers 'Content-Type, User-Token, X-Auth-Token';
            add_header Access-Control-Max-Age 1728000;
            add_header Content-Type 'text/plain; charset=utf-8';
            add_header Content-Length 0;
            return 204;
        }

        # 添加 CORS 头
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
        add_header Access-Control-Allow-Headers 'Content-Type, User-Token, X-Auth-Token';
        
        # 缓存配置
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

启用配置并启动服务

Linux:

bash

# 创建静态文件目录
sudo mkdir -p /var/www/static

# 启用站点配置
sudo ln -s /etc/nginx/sites-available/ccxc-dev /etc/nginx/sites-enabled/

# 测试配置
sudo nginx -t

# 启动 Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

Windows:

cmd

# 测试配置
nginx -t

# 启动 Nginx
nginx

组件部署

1. 主后端 (ccxc-backend)

获取源码

bash

# 克隆仓库
git clone https://github.com/cipherpuzzles/ccxc-backend.git
cd ccxc-backend

# 或下载指定版本
wget https://github.com/cipherpuzzles/ccxc-backend/archive/refs/tags/v1.0.0.tar.gz
tar -xzf v1.0.0.tar.gz
cd ccxc-backend-1.0.0

编译和运行

使用 Visual Studio:

打开 ccxc-backend.sln
选择 Debug 或 Release 配置
指定目标架构（推荐 x64）
按 F5 运行

使用 .NET CLI:

bash

# 还原依赖
dotnet restore

# 编译项目（指定架构）
dotnet build --configuration Release --runtime win-x64

# 运行项目
dotnet run --project ccxc-backend --configuration Release

配置文件

首次运行后，在 ccxc-backend/bin/x64/Release/net8.0/Config/ 目录下会生成 ccxc.config.toml 配置文件：

toml

# 继承的配置文件。本配置文件中未定义的配置项将从继承的配置文件中继承。
extends = []
# 混入的配置文件。覆盖本配置文件中的同名配置项。
mixin = []

["Config/CcxcConfig"]
# HTTP服务端口
HttpPort = ""
# Redis服务器连接字符串
RedisConnStr = ""
# 数据库连接字符串
DbConnStr = "Server=localhost;User=ccxc_user;Database=ccxc_dev;Port=3306;Password=your_secure_password;Charset=utf8mb4;ConvertZeroDateTime=True"
# 调试模式：调试模式打开时，捕获的异常详情将通过HTTP直接返回给客户端，关闭时只返回简单错误消息和500提示码。True-打开 False-关闭，默认为False
DebugMode = ""
# 插件目录，插件将会存放在这里。默认：Plugins
PluginDir = ""
# 图片存储目录，上传的图片将会存放在这里。请注意：必须使用绝对路径！
ImageStorage = "/var/www/static/images/"
# 图片访问前缀。请注意需要有 /static/images/
ImagePrefix = "https://static.ccxc.ikp.yt:22443/static/images/"
# 密码Hash种子1 （请生成随机字符串）
PassHashKey1 = "your_random_seed_1"
# 密码Hash种子2 （请生成随机字符串）
PassHashKey2 = "your_random_seed_2"
# AES Master Key，请自由设置，切记不要泄露
AESMasterKey = "your_32_character_aes_master_key"
# 启用邮件验证。默认启用（True-启用 False-禁用）
EnableEmailVerify = "True"
# 阿里云邮件推送服务Access Key
AliyunDmAccessKey = "your_aliyun_dm_access_key"
# 阿里云邮件推送服务Access Secret
AliyunDmAccessSecret = "your_aliyun_dm_access_secret"

配置说明

如果暂时不启用邮件验证，将 EnableEmailVerify 设置为 false
ImageStoragePath 必须是可写的绝对路径
种子和密钥请使用随机生成的安全字符串

修改配置文件后重新运行服务。

2. 消息与同步服务器 (ccxc-sync-server)

获取源码并安装依赖

bash

# 克隆仓库
git clone https://github.com/cipherpuzzles/ccxc-sync-server.git
cd ccxc-sync-server

# 安装依赖
npm install

配置文件

将 config.default.json 复制为 config.json，然后根据需要修改：

json

{
    "redis": {
        "host": "localhost",
        "port": 6379
    },
    "yPersistence": {
        "dir": "./data"
    },
    "apiRoot": "http://localhost:52412/api/v1"
}

启动服务

bash

# 开发模式启动
npm run start

3. 后台管理面板 (ccxc-admin)

获取源码并安装依赖

bash

# 克隆仓库
git clone https://github.com/cipherpuzzles/ccxc-admin.git
cd ccxc-admin

# 安装依赖
npm install

环境配置

编辑 .env.development 文件：

bash

# API 后端地址（通过 Nginx 代理）
VITE_BACKEND_ROOT=https://api.ccxc.ikp.yt:22443/api

启动开发服务器

bash

# 启动开发服务器
npm run dev

服务启动后，访问显示的本地地址（通常是 https://admin.ccxc.ikp.yt:5137）。

4. 主站前端 (ccxc-website)

获取源码并安装依赖

bash

# 克隆仓库
git clone https://github.com/cipherpuzzles/ccxc-website.git
cd ccxc-website

# 安装依赖
npm install

环境配置

编辑 .env.development 文件：

bash

# API 后端地址
VITE_BACKEND_ROOT=https://api.ccxc.ikp.yt:22443/api

启动开发服务器

bash

# 启动开发服务器
npm run dev

服务启动后，访问 https://www.ccxc.ikp.yt:13880。

5. 谜题前端 (ccxc-puzzle)

获取源码并安装依赖

bash

# 克隆仓库
git clone https://github.com/cipherpuzzles/ccxc-puzzle.git
cd ccxc-puzzle

# 安装依赖
npm install

环境配置

编辑 .env.development 文件：

bash

# API 服务地址
VITE_API_ROOT=https://api.ccxc.ikp.yt:22443/api/v1

# WebSocket 同步服务地址
VITE_WS_HOST=wss://api.ccxc.ikp.yt:22443/ws-api

# 主站地址
VITE_WEBSITE_MAIN=https://www.ccxc.ikp.yt:13880

启动开发服务器

bash

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

服务启动后，访问 https://puzzle.ccxc.ikp.yt:20480。

谜题前端说明

ccxc-puzzle 是高度可定制的组件，通常每届比赛都会基于此进行二次开发以适应特定的谜题类型和交互需求。

系统初始化

1. 验证服务状态

确保所有组件正常运行：

bash

# 检查 MariaDB
mysql -u ccxc_user -p -e "SELECT 1;"

# 检查 Redis
redis-cli ping

# 检查 Nginx
curl -k https://api.ccxc.ikp.yt:22443/v1

# 检查各个前端服务
curl -k https://www.ccxc.ikp.yt:13880
curl -k https://admin.ccxc.ikp.yt
curl -k https://puzzle.ccxc.ikp.yt:20480

2. 访问主站并注册用户

访问 https://www.ccxc.ikp.yt:13880
点击"注册"创建第一个用户账号
完成注册流程
进入个人中心，记录你的 UID（通常为 1）

3. 设置系统管理员

找到 ccxc-backend 的可执行文件：

Windows (.NET CLI 构建):

cmd

cd ccxc-backend\bin\x64\Release\net8.0
ccxc-backend.exe initadmin

Linux/macOS:

bash

cd ccxc-backend/bin/x64/Release/net8.0
./ccxc-backend initadmin

Visual Studio 构建:

cmd

cd ccxc-backend\bin\x64\Release\net8.0
ccxc-backend.exe initadmin

按照程序提示输入刚才注册用户的 UID，该用户将被设置为系统管理员。

4. 访问管理后台

访问 https://admin.ccxc.ikp.yt:5137/userbackend （在管理后台地址后加 /userbackend）
使用管理员账号登录
如果一切正常，你应该能看到管理后台界面

故障排除

常见问题

1. HTTPS 证书错误

确保已正确安装 mkcert 并执行 mkcert -install
检查 Nginx 配置中的证书路径是否正确

2. 数据库连接失败

验证 MariaDB 服务是否运行：sudo systemctl status mariadb
检查数据库连接字符串是否正确
确认用户权限是否正确设置

3. 前端无法连接后端

检查 Nginx 是否正常运行并正确代理
验证防火墙设置
确认各服务端口是否被占用

4. WebSocket 连接失败

检查 ccxc-sync-server 是否正常运行
验证 Nginx WebSocket 代理配置
确认 Redis 连接正常

日志查看

ccxc-backend 的日志会写入可执行文件所在目录的 ./log 中。以日期 yyyyMMdd.log 命名。

开发建议

使用 IDE 的调试功能进行后端开发
利用浏览器开发者工具调试前端问题
定期备份开发数据库
使用 Git 进行版本控制和协作开发

下一步

开发环境搭建完成后，你可以：

阅读快速入门了解网站功能和基本使用
阅读 API 文档了解接口规范
查看部署指南了解生产环境部署
参考插件开发进行功能扩展
查看密码菌 Github 参与开源贡献

开发环境搭建 ​

系统要求 ​

操作系统 ​

开发工具 ​

必需中间件 ​

数据库 ​

缓存与消息队列 ​

Web 服务器 ​

架构概览与端口规划 ​

服务架构图 ​

端口分配表 ​

环境准备 ​

1. 安装 HTTPS 证书工具 ​

2. 生成开发证书 ​

3. 配置 MariaDB ​

安装 MariaDB ​

创建数据库和用户 ​

4. 配置 Redis ​

安装 Redis ​

启动 Redis ​

验证安装 ​

5. 配置 Nginx ​

安装 Nginx ​

配置文件 ​

启用配置并启动服务 ​

组件部署 ​

1. 主后端 (ccxc-backend) ​

获取源码 ​

编译和运行 ​

配置文件 ​

2. 消息与同步服务器 (ccxc-sync-server) ​

获取源码并安装依赖 ​

配置文件 ​

启动服务 ​

3. 后台管理面板 (ccxc-admin) ​

获取源码并安装依赖 ​

环境配置 ​

启动开发服务器 ​

4. 主站前端 (ccxc-website) ​

获取源码并安装依赖 ​

环境配置 ​

启动开发服务器 ​

5. 谜题前端 (ccxc-puzzle) ​

获取源码并安装依赖 ​

环境配置 ​

启动开发服务器 ​

系统初始化 ​

1. 验证服务状态 ​

2. 访问主站并注册用户 ​

3. 设置系统管理员 ​

4. 访问管理后台 ​

故障排除 ​

常见问题 ​

日志查看 ​

下一步 ​

开发环境搭建

系统要求

操作系统

开发工具

必需中间件

数据库

缓存与消息队列

Web 服务器

架构概览与端口规划

服务架构图

端口分配表

环境准备

1. 安装 HTTPS 证书工具

2. 生成开发证书

3. 配置 MariaDB

安装 MariaDB

创建数据库和用户

4. 配置 Redis

安装 Redis

启动 Redis

验证安装

5. 配置 Nginx

安装 Nginx

配置文件

启用配置并启动服务

组件部署

1. 主后端 (ccxc-backend)

获取源码

编译和运行

配置文件

2. 消息与同步服务器 (ccxc-sync-server)

获取源码并安装依赖

配置文件

启动服务

3. 后台管理面板 (ccxc-admin)

获取源码并安装依赖

环境配置

启动开发服务器

4. 主站前端 (ccxc-website)

获取源码并安装依赖

环境配置

启动开发服务器

5. 谜题前端 (ccxc-puzzle)

获取源码并安装依赖

环境配置

启动开发服务器

系统初始化

1. 验证服务状态

2. 访问主站并注册用户

3. 设置系统管理员

4. 访问管理后台

故障排除

常见问题

日志查看

下一步