CTFNote二次开发指南：从本地开发环境搭建到Pull Request提交工作流

CTFNote二次开发指南从本地开发环境搭建到Pull Request提交工作流【免费下载链接】CTFNoteCTFNote is a collaborative tool aiming to help CTF teams to organise their work.项目地址: https://gitcode.com/gh_mirrors/ct/CTFNoteCTFNote是一款面向 CTF 战队的开源协作工具可集中管理比赛信息、任务清单、解题进度与队伍权限。本篇CTFNote 二次开发指南面向新手使用 Docker Compose 快速完成本地开发环境搭建并梳理从功能分支到 Pull Request 提交的完整工作流帮你高效上手为 CTFNote 添加功能或修复 Bug。一、30 秒认识 CTFNote 代码结构CTFNote 采用前后端分离架构仓库主要由三大模块组成目录技术栈职责api/TypeScript Express PostGraphileGraphQL API、SQL 数据库迁移、Discord 机器人集成front/Vue 3 Quasar Apollo ClientWeb 前端界面与 GraphQL 查询db/PostgreSQL数据库镜像与多库初始化脚本以下关键文件建议优先阅读docker-compose.dev.yml开发环境只需容器化启动数据库和 Hedgedoc 笔记服务前后端以热重载方式在本地运行api/src/index.tsAPI 启动入口服务启动前会自动执行 api/migrations/ 目录中尚未运行的全部 SQL 迁移front/quasar.conf.js前端开发服务器配置将/graphql、/pad等请求代理到本地 API 与笔记服务CTFNote 协作工具的核心界面——CTF 比赛列表点击任一比赛即可进入任务管理二、本地开发环境搭建Docker Compose 快速启动2.1 前置要求与克隆仓库准备 Docker含 Compose 插件与 Yarn仓库通过packageManager字段锁定为 Yarn 4.1.1然后克隆仓库git clone https://gitcode.com/gh_mirrors/ct/CTFNote cd CTFNote2.2 安装根目录依赖并启用 Git Hooksyarn这一步会自动执行prepare脚本通过 Husky 安装 pre-commit 钩子见 .husky/pre-commit提交前自动运行 Prettier 格式化与 lint-staged 检查是保证代码风格一致的第一道防线。✅2.3 一键启动数据库与协作笔记服务docker compose -f docker-compose.dev.yml up -d hedgedoc db该命令基于 db/Dockerfile 启动 PostgreSQL同时创建ctfnote与hedgedoc两个数据库并拉起 Hedgedoc——CTFNote 任务页内嵌的共享笔记Pad正是由它提供2.4 启动 GraphQL API热重载cd api yarn # 安装依赖 yarn dev # 开发模式启动支持热重载API 默认监听 3000 端口。开发模式下api/src/index.ts 会额外开启 GraphiQL 图形化调试界面和数据库结构变更监听。本地配置已就绪仓库中api/.env已指向.env.dev数据库指向localhost:5432。2.5 启动 Quasar 前端热重载新开一个终端执行cd front yarn # 安装依赖 yarn dev # 启动 Quasar 开发服务器前端默认运行在 8088 端口/graphql、/uploads、/calendar.ics、/pad等请求会被自动代理到后端服务。2.6 验证开发环境是否就绪服务地址说明Web 界面http://localhost:8088/Quasar 前端GraphQL APIhttp://localhost:3000/Express PostGraphileGraphiQLhttp://localhost:3000/graphiqlGraphQL 调试控制台Hedgedochttp://localhost:3001/共享笔记服务打开 Web 界面注册第一个账号自动获得管理员权限看到下方的任务列表页即说明本地开发环境搭建完成 三、二次开发高频场景实操3.1 前端修改页面并新增 GraphQL 查询页面组件位于 front/src/pages/如CTF.vue、Task.vue业务封装在 front/src/ctfnote/。新增或修改 GraphQL 查询时按 3 步走在 front/src/graphql/ 中编写.graphql查询文件在front目录执行yarn codegen按 codegen.yml 重新生成 front/generated/graphql.ts 类型定义在页面中通过 Apollo Client 组合式函数调用生成的查询。⚠️ CI 会执行graphql-codegen --check校验生成文件是否为最新漏跑 codegen 会导致构建失败。3.2 后端扩展 GraphQL 与编写数据库迁移新增 GraphQL 字段/类型在 api/src/plugins/ 编写 PostGraphile 插件并在 api/src/index.ts 的appendPlugins数组中注册变更表结构在 api/migrations/ 按序号追加新的.sql文件如57-your-change.sqlAPI 每次启动都会自动执行未运行的迁移。3.3 生产环境部署可选了解二次开发完成后可用根目录 docker-compose.yml 构建完整生产镜像docker compose up -d --build构建需 3 GB 以上内存。在 .env 中按需配置域名、TLS、Discord 机器人等选项管理后台还支持自定义团队主题配色四、Pull Request 提交工作流4 步完成合入CTFNote 的协作流程记录在 CONTRIBUTING.md遵循以下 4 步第 1 步创建功能分支分支以关联的 issue 编号命名没有关联 issue 时以0-开头git checkout -b 132-add-new-feature # 有 issue 时 git checkout -b 0-contribution-guide # 无 issue 时第 2 步本地自检pre-commit 钩子会自动格式化代码也可在api与front目录手动执行yarn lint和yarn build提前暴露问题。第 3 步推送并发起 Pull RequestPR 目标分支为官方仓库的main分支。功能未完成时可先创建 PR标题加上WiP:前缀表明该请求仍在开发中。第 4 步通过 CI 与代码评审CI 流程.github/workflows/ci.yml会自动完成 4 项检查在 Node.js 18 / 19 / 20 三个版本下分别构建前后端用pg-validate-migrations校验数据库迁移文件合法性运行迁移后校验 GraphQL 代码生成文件是否为最新执行 ESLint 与 Prettier 风格检查。全部通过后仍需维护者maintainer评审同意方可合并。五、常见问题速查问题解决方式端口被占用3000/3001/5432/8088修改 docker-compose.dev.yml 的端口映射或调整 front/quasar.conf.js 的devServer配置及代理目标API 启动报数据库错误用docker compose -f docker-compose.dev.yml ps确认 db 容器已就绪必要时删除数据卷重建环境修改.graphql后前端类型报错在front目录重新执行yarn codegen生成最新类型生产环境用户频繁掉线见 api/src/index.tsSESSION_SECRET不足 64 位时会随机生成密钥需在.env中配置固定值小结记住docker compose -f docker-compose.dev.yml up -d hedgedoc dbyarn dev的组合你就拥有了完整的 CTFNote 本地开发环境遵循「issue 分支 → 本地自检 → 发起 PR可用 WiP 前缀→ CI 评审」的流程你的二次开发改动就能顺利进入 main 分支。祝开发顺利【免费下载链接】CTFNoteCTFNote is a collaborative tool aiming to help CTF teams to organise their work.项目地址: https://gitcode.com/gh_mirrors/ct/CTFNote创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考