contest-bitnp 国防知识竞赛

Note

GitHub 全年都会报告 Django 安全漏洞，而本项目只在夏秋之交使用。为减轻维护压力，每年会存档仓库；解除存档请联系管理员。

目录

• 开发
  • 开始
    • ⚒️ 安装工具
    • 👢 安装包
    • 🏃‍♀️ 启动服务器
    • ✅ 检查
  • VS Code
    • 任务
    • Django 魔法
• 部署
  • 容器部署
    • 准备工作
    • 构建容器镜像
    • 从头开始使用容器进行部署
  • 手动部署

开发

技术细节请参考doc/。

Note

还可参考 GitHub Actions。

开始

⚒️ 安装工具

Poetry

• 功能：本项目使用 管理 python 包。

  例如poetry shell可在终端直接使用虚拟环境。

• 安装方法：请参阅 Introduction | Documentation | Poetry。

• 配置

  完成安装后，建议您选择将虚拟环境放在项目中：

  $ poetry config virtualenvs.in-project true

  原因：这样poetry install时会在项目所在文件夹创建.venv/，比C:/Users/…/AppData/Local/pypoetry/Cache/…或~/.cache/pypoetry/…更明显。

Just

• 功能：本项目源代码不在根目录，有许多命令执行时有 tricks。因此建议安装 just，用 just 调用。

  例如，运行 mypy 时，必须使用正确配置在正确的位置运行。

  $ just --list  # 列出可用任务

• 安装方法（Unix）

  建议参考 Packages - Just Programmer's Manual，使用包管理器安装。

• 安装方法（Windows）

  下载编译好的可执行文件，解压出just.exe，放到$PATH环境变量包含的任意地方。另外也可用包管理器 scoop 安装：

  > scoop install just

  在 Windows 上，除了 just，您还需要选个 shell。至少有下面几种选择。

  • 将C:/Program Files/Git/bin/添加到$PATH环境变量，使用 Git for Windows 附带的 Git Bash（sh.exe）。

  • 也使用 Git Bash，但不用环境变量，而用 scoop 包装：创建~/scoop/shims/sh.shim，写入path = "C:/Program Files/Git/usr/sh.exe"。

  • 编辑项目根目录的justfile，使用 Command Prompt 或 PowerShell。

    # 在 justfile 开头加上以下任意一行
    set shell := ["cmd.exe", "/c"]
    set shell := ["powershell.exe", "-c"]
    # 更改后请勿提交到仓库中，因为CI和每人的设备不一样。

  Note

  C:/Program Files/Git/指 Git 的安装目录。

  另外注意是…/Git/bin/，而非…/Git/usr/bin/。

  Note

  可用--shell临时测试，例如：

  $ just --shell 'C:/Program Files/Git/usr/bin/bash.exe' …

• 配置

  如果需控制 just 使用哪个 python，请在项目根目录创建.env文件，设置PYTHON变量。下面是一些例子。

  # 使用项目中的虚拟环境
  PYTHON = "./.venv/Scripts/python.exe"
  
  # 使用 poetry 缓存中的环境
  PYTHON = "C:/Users/bjalp/AppData/Local/pypoetry/Cache/virtualenvs/…/python.exe"
  
  # 直接调用 poetry（万能，但比较慢）
  PYTHON = "poetry run python"

  Note

  poetry install创建虚拟环境后，可用poetry env info查看“Executable”的位置。

Pnpm

• 功能：构建前端 CSS 和 JavaScript。

• 安装方法

  1. 前往 Node.js 网站，下载并安装 v18 LTS。（安装结束后会提示安装 choco，可取消勾选）

  2. 使用 corepack 安装 pnpm。

     $ corepack enable
     $ corepack prepare pnpm@latest --activate

  Note

  也可尝试 Installation | pnpm 介绍的其它方法。

👢 安装包

初次使用时，需要安装项目依赖的包并创建数据库：

$ just update

以后拉取他人提交后，如果他人更新了依赖或更改了数据模型，你可能无法继续开发，此时也请just update。

🏃‍♀️ 启动服务器

1. 构建前端。

   $ just build-js build-theme

   Note

   如果你想更改前端代码，可just watch-js、just watch-theme来自动重新构建。

2. 启动 Django 服务器。

   $ just serve

3. 访问 localhost:8000，用户名、密码请咨询他人。

✅ 检查

• 代码质量

  $ just check-all

  这会检查类型、运行测试等。

• 格式（可选）

  本项目配置了 pre-commit，可自动格式化代码、检查错别字等。

  如果你想使用它，那么可用 pip 或 pipx 安装 pre-commit，然后运行pre-commit install。此后提交到仓库时会自动检查格式。

  Note

  git commit --no-verify可绕过 pre-commit。

VS Code

任务

部分 just 命令配备了 problem matcher。Ctrl+P，输入task及空格，按提示操作可运行。

Django 魔法

VS Code 默认的 Pylance 无法识别很多 Django 魔法（如*_set）。可考虑禁用之，代以 Matan Gover 的 Mypy。（也可并用）这需要你在工作区设置mypy.dmypyExecutable，目前的设置仅适用于 Windows。

部署

容器部署

准备工作

为减小镜像，用 pip 替代 poetry，需将pyproject.toml的tool.poetry.dependencies、tool.poetry.group.deploy.dependencies转换为requirements.txt。

$ poetry export --output requirements.txt --without-hashes --without-urls --with deploy

Note

现在仓库中的requirements.txt还手动删除了python_version、sys_platform，没考虑 python 版本、操作系统不同的问题。之后出问题了再改。

构建容器镜像

$ git clone https://github.com/BITNP/contest-bitnp
$ cd contest-bitnp
$ docker build -t everything411/contest-bitnp .

构建过程中会做以下几件事：

1. 用 pnpm 构建前端。
2. 设置用于生产的环境变量。
3. 安装依赖，整理静态文件，添加题库，启动服务。

从头开始使用容器进行部署

编写docker-compose.yml

version: "3"
services:
  web:
    image: everything411/contest-bitnp
    ports:
      - 8080:80
    environment:
      - SECRET_KEY=${SECRET_KEY}
      - DJANGO_PRODUCTION=1
    volumes:
     - ./db:/usr/src/app/db              # 数据库持久化
     - ./fixtures:/usr/src/app/fixtures  # 放fixtures，加载题目用
     # - ./settings.py:/usr/src/app/contest/settings.py # 取消注释可临时调整设置

然后

$ mkdir db
$ docker compose up -d

然后进去容器内部，创建超级管理员账号，导入：

$ docker exec -it contest_web_1 bash
(in container) # python manage.py createsuperuser
(in container) # python manage.py loaddata fixtures/*.yml

手动部署

需要 poetry、just，安装方法及配置请参考上文。

Note

可用python -m venv替代 poetry，手动执行替代 just。

$ export DJANGO_PRODUCTION="任何非空字符串"
$ export SECRET_KEY="The secret key must be a large random value and it must be kept secret"

$ echo 'PYTHON = "./.venv/bin/python"' > .env
$ just update  # 安装依赖、数据库等
$ just check-deploy  # 检查

Note

若希望部署时永远开放答题，请export DJANGO_DISABLE_QUIZ_OPENING_TIME_INTERVAL="任何非空字符串"。

在 poetry 中安装部署依赖组后，可以使用 uvicorn 或者 gunicorn 来运行本网站：

使用 uvicorn 单线程运行：

$ export DJANGO_PRODUCTION=1
$ export SECRET_KEY="!!replace me replace me!!"
$ cd contest-bitnp
$ uvicorn contest.asgi::application

或者使用 gunicorn 管理多个 uvicorn 工作进程：

$ export DJANGO_PRODUCTION=1
$ export SECRET_KEY="!!replace me replace me!!"
$ cd contest-bitnp
$ gunicorn -w 4 -k uvicorn.workers.UvicornWorker contest.asgi:application

另请参阅 How to deploy Django | Django documentation | Django。