# adp_zstack_v3

**Repository Path**: andisec/adp_zstack_v3

## Basic Information

- **Project Name**: adp_zstack_v3
- **Description**: 靶场后端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-03
- **Last Updated**: 2025-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

The code repository:
```http request
http://172.16.1.30:7800/adp/adp_v2.0/-/tree/v2.1_feature
```

## 一、项目结构

```
.
├── README.md
├── app
│         ├── __init__.py
│         ├── api  # 接口
│         │     ├── __init__.py
│         │     └── v1  # 版本
│         │         ├── admin  # 管理员模块
│         │         │         ├── __init__.py
│         │         │         ├── base_view.py
│         │         │         ├── urls.py
│         │         │         └── ......
│         │         ├── auth  # 认证模块
│         │         │         ├── __init__.py
│         │         │         ├── urls.py
│         │         │         └── views.py
│         │         ├── collector
│         │         │         ├── __init__.py
│         │         │         ├── urls.py
│         │         │         └── views.py
│         │         ├── organizer  # 组织者模块
│         │         │         ├── __init__.py
│         │         │         ├── base_view.py
│         │         │         ├── ......
│         │         │         ├── path  # 内置课件
│         │         │         │         ├── xxxxxx.pptx
│         │         │         │         ├── ......
│         │         │         │         └── xxxxxx.pdf
│         │         │         ├── signal  # 信号
│         │         │         │         ├── __init__.py
│         │         │         │         └── red_blue.py
│         │         │         └── urls.py
│         │         ├── participant  # 学生端模块
│         │         │         ├── __init__.py
│         │         │         ├── base_view.py
│         │         │         ├── ......
│         │         │         └── urls.py
│         │         └── permission  # 权限模块
│         │                   ├── __init__.py
│         │                   ├── base_view.py
│         │                   ├── urls.py
│         │                   └── views.py
│         ├── command  # 自定义click命令
│         │         ├── __init__.py
│         │         ├── command.py
│         │         ├── init_permission.py  # 初始化权限
│         │         ├── ishell.py  # ipython支持的flask shell
│         │         └── role_filter.py  # 手动添加访问策略
│         ├── common  # 接口中公共方法
│         │         ├── __init__.py
│         │         ├── decorators.py  # 装饰器
│         │         ├── libs  # 视图依赖
│         │         │         ├── __init__.py
│         │         │         ├── authentication.py
│         │         │         ├── permission.py
│         │         │         └── time_jws.py
│         │         └── rule.py
│         ├── models  # sqlalchemy model存放位置
│         │         ├── __init__.py
│         │         ├── baseModel.py
│         │         └── ......
│         └── role_control
│             └── __init__.py  # 角色权限控制器
├── configs  # 配置文件夹
│         ├── __init__.py
│         ├── development.configs.yaml  # 环境配置文件，命名规则：`环境` + `.configs.yaml`
│         ├── load_config.py  # 加载yaml文件脚本
│         ├── log_config.py  # 日志配置
│         ├── range_flag.yaml  # 靶场预设flag
│         ├── settings.py  # 核心配置文件
│         └── template_images_list.yaml  # 靶场镜像文件
├── deploy  # 部署文件夹
│         ├── base.Dockerfile  # 基础镜像
│         ├── dev
│         │         ├── docker-compose.yml
│         │         ├── start.sh
│         │         └── uwsgi.ini
│         ├── scripts
│         │         ├── check_container.sh
│         │         ├── cleanDocker.sh
│         │         ├── deploy.sh
│         │         └── test_deploy.sh
│         ├── test
│         │         ├── docker-compose.yml
│         │         ├── start.sh
│         │         └── uwsgi.ini
│         ├── uvicorn_worker.py
│         └── worker_config.py  # gunicorn配置
├── logs  # 日志目录
│         ├── error_2022-07-20.log
│         └── info_2022-07-20.log
├── monitor
│         ├── async_update.py
│         ├── data_monitor.py
│         ├── log_schedule_handler.py
│         ├── redis_pool.py
│         └── update_value.py
├── core  # 重载的flask、openstack方法
│         ├── __init__.py
│         ├── ext_flask.py  # 重载Blueprint及Rule
│         ├── ext_flask_restful.py  # 重载flask_restful Api
│         └── openstack_connect.py  # 重载openstack connect
├── scripts  # 脚本
│         ├── add_chengdu_range.py
│         ├── add_range.py
│         ├── add_system_course.py
│         ├── add_system_range.py
│         ├── initial_db.py
│         ├── redis_delete_vm.py
│         ├── redis_pub_sub.py
│         ├── scripts_log.py
│         └── set_config_file.py
├── tasks  # celery任务目录
│         ├── __init__.py
│         └── tasks.py
├── tests  # 单元测试
│         ├── __init__.py
│         ├── add_test_data.py
│         ├── common
│         │         ├── __init__.py
│         │         ├── fixtures.py
│         │         └── utils.py
│         ├── ssh_connect.py
│         ├── test_basics.py
│         ├── test_user_model.py
│         └── tests.py
├── tools  # 仅项目依赖拓展
│         ├── __init__.py
│         ├── celery_ext.py  # celery拓展
│         └── extensions.py  # db，redis，cache拓展
├── pytest.ini  # pytest配置文件
├── releaseSpace.py
├── utils  # 项目使用的组件
│   ├── __init__.py
│   ├── captcha
│   │         ├── __init__.py
│   │         ├── captcha.py
│   │         └── fonts
│   ├── crypto.py  # 加密模块
│   ├── enums.py  # 枚举
│   └── utils.py  # 其他工具方法
│
├── celery_worker.py  # celery启动入口
│
└── manage.py  # 项目及脚本启动入口
```

## 二、项目启动与管理命令

在部署openstack后

- 部署环境
  - nginx
    参考 `deploy/nginx/nginx_feature.conf` 文件编辑修改前端项目位置及后端服务端口
  - mysql/redis
    - 修改 `configs/development.configs.yaml` 文件中 mysql/redis 配置
    - 默认mysql/redis密码已加密，加密前密码为 `adp@123`、`abc!@#2021`
  - 其他配置修改
    - openstack连接配置
  - pyenv
    如果系统非自带python 3.7 如 ubuntu 18.04,
    从 http://172.16.3.203:23333 下载 `pyenv-master.zip`, `pyenv-virtualenv-master.zip`, `Python-3.7.13.tar.xz`
    ```shell
    su root && cd;
    unzip pyenv-master.zip && unzip pyenv-virtualenv-master.zip;
    mv pyenv-master ~/.pyenv && cd ~/.pyenv && src/configure && make -C src;
    echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc;
    echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc;
    echo 'eval "$(pyenv init -)"' >> ~/.bashrc;
    source ~/.bashrc;
    mv pyenv-virtualenv-master $(pyenv root)/plugins/pyenv-virtualenv;
    echo 'eval "$(pyenv virtualenv-init -)"' >> ~/.bashrc;
    source ~/.bashrc;
    mkdir -p ~/.pyenv/cache && mv Python-3.7.13.tar.xz ~/.pyenv/cache && pyenv install 3.7.13;
    pyenv virtualenv 3.7.13 adp;
    pyenv activate adp && pip install -r adp_complete/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
    ```
  - supervisor启动
    参考 `deploy/supervisor/adp_complete.ini` 修改相关配置
  - 脚本启动
    参考 `deploy/run/start_all.sh` 进行修改相关配置
  - docker 启动
    从 http://172.16.3.203:23333 下载 `adp_complete_base-1.0.tar`
    ```shell
    docker load -i adp_complete_base-1.0.tar
    cd adp_complete && docker-compose -f deploy/docker-compose.yml up -d
    ```

- 初始化数据及数据库：
    ```shell
    # 迁移数据库
    flask deploy
    # 初始化权限
    flask init_permission -s json -sw y
    # 初始化镜像
    flask init_image
    # 添加系统靶场
    flask add_range
    # 添加系统赛题及内置赛题
    flask add_issue
    # 添加内置课程, 按提示继续操作
    cd scripts && python add_system_course.py
    ```

- 项目部署启动参考deploy目录
- 线上调试请通过
    ```shell
    flask ishell
    ```


### 1. 项目启动

> 推荐gunicorn
> 注：当app指定为工厂方法时（app:create_app()），接口性能与指定具体app的方式比性能较弱

  - wsgi
    ```shell
    # flask
    flask run  # 需要自行预先配置DEBUG等环境变量

    # or manage.py
    python manage.py runserver  # 自动读取config.yaml配置

    # or gunicorn （配置见 deploy/worker_config.py）
    gunicorn -c deploy/worker_config.py manage:app
    gunicorn -w 4 --threads 2 -b 0.0.0.0:8000 "app:create_app()" -k gevent --log-level=debug
    gunicorn -w 4 --threads 2 -b 0.0.0.0:8000 manage:app -k gevent --log-level=debug

    # or uwsgi (配置见 deploy/uwsgi.ini)
    uwsgi --ini uwsgi.ini
    uwsgi --http :5000 -w "app:create_app()" -p 4 --threads 6
    ```
  - asgi
    ```shell
    # 使用uvicorn worker
    gunicorn -w 4 --threads 2 -b 0.0.0.0:8000 "app:create_asgi_app()" -k deploy.uvicorn_worker.SQUvicornWorker
    ```

### 2. 项目管理命令
  - 管理命令
    终端输入flask，按提示输入命令
    ```shell
    flask

    # 输出
    Usage: flask [OPTIONS] COMMAND [ARGS]...
      ...
    Commands:
      add_ctf_red_blue_role  添加红蓝比赛角色
      db                     Perform database migrations.
      deploy                 迁移数据库.
      example                自定义命令行示例
      init_permission        初始化权限
      ishell                 flask shell 的 ipython 支持版本
      releaseSpace           销毁已过期的虚拟机
      routes                 Show the routes for the app.
      run                    Run a development server.
      shell                  Run a shell in the app context.
      syncFlow
      operate_image          操作虚拟机镜像
      init_image             初始化镜像
    ```

  - 上下文调试
    ```shell
    # python shell
    flask shell

    # ipython 支持
    flask ishell
    ```

## 三、测试

### 单元测试
执行测试用例
```shell
python manage.py test
```

# 性能测试

> pip install py-spy

## 使用火焰图查看性能
```shell
sudo py-spy record -o profile.svg -- gunicorn -w 8 --threads 2 -b 0.0.0.0:5000 manage:app
sudo py-spy record -o profile.svg -- uwsgi --http :5000 -w manage:app -p 8 --threads 2
```

## 四、数据库迁移

```shell
 python manage.py deploy
```


## 五、Git规范

http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html
https://www.conventionalcommits.org/en/v1.0.0/

git commit 时，type建议使用约定成俗的类型，如下

| type | 说明                |
| ---- |-------------------|
|   feat  | 新功能               |
|   fix   | 修复                |
|   hotfix  | 线上环境修复            |
|   perf  | 功能优化              |
|   chore / ci   | 构建过程或辅助工具的变动      |
|   docs   | 文档                |
|   style   | 不涉及代码逻辑的格式化变动     |
|   refactor   | 重构（既不是新增功能、也不是bug修复） |
|   test   | 测试                |
|   config   | 配置文件              |

- 强制规范
  终端下进入项目目录，执行
  ```shell
  pre-commit install
  ```

  部分情况下可能需要忽略代码风格校验, 不修改相关配置文件前提下有如下方式可以临时关闭
  ```shell
  flake8
      - 文件首添加: # flake8: noqa F401,B950
      - 代码行末添加: print("abc")  # noqa

  pylint
      - 文件首或行末:  # pylint:disable=R0903,E1120
      - 代码段: def func():  # pylint: disable=all
                   ...
  ```

- 提交示例
  ```shell
  > git commit -m "feat(可选模块名): 新增内容
  >
  > 新增内容详细说明（可选）
  >
  > close 禅道#100（可选, 建议header部分说明）
  "
  ```

  ```shell
  > revert "feat(可选模块名): 新增内容"
  ```

  ```shell
  # 仅用于触发ci重新部署
  > git commit -m "chore(deploy): 重新部署"
  ```


## 六、项目公共方法、组件使用说明

### Celery
- 任务注册
  * `tasks/tasks.py`, `app.api`及其子模块中`tasks.py`文件（或其他符合celery任务目录结构文件）将被自动发现
  * 如果任务未注册，尝试在其当前模块 `__init__.py` 文件中手动注册，或在`tasks.celery_ext.create_celery_app`中导入

- 任务编写
  ```python
  from tools import celery_app

  @celery_app.task(bind=True)
  def example(self):
      print('Request: {0!r}'.format(self.request))
  ```

- celery启动
  ```shell
  # 按实际队列启动
  celery -A celery_worker.celery_app worker -l INFO -Q celery --autoscale 8,1
  ```

### Flask-SQLAlchemy / SQLAlchemy

```python
from tools import db
```

### Redis

```python
# redis链接池
from tools import redis_conn
```

### Cache

```python
from tools import cache
```

### AES加解密

```python
from utils.crypto import Crypt

# 兼容
# Crypt = Crypt()

encrypt_value = Crypt.encrypt('123123')
print(encrypt_value)

decrypt_value = Crypt.decrypt(encrypt_value)
print(decrypt_value)
```

启动程序， --host 指定ip --port 端口，如：
```shell
python manage.py runserver --host 127.0.0.1 --port 5000
```

## 七、项目权限设计

核心思想，每个蓝图为系统不同模块，模块下含有子路由若干，要求做到最小代码侵入实现角色权限控制

为不同蓝图或路由指定 `app/role_control/__init__.py`