From 7ddafef65d6b560774e5d0580d5becb747833cd6 Mon Sep 17 00:00:00 2001 From: hequan2017 Date: Mon, 28 Sep 2026 11:51:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E5=86=99=E4=B8=AD=E8=8B=B1?= =?UTF-8?q?=E6=96=87=20README=EF=BC=8C=E6=96=B0=E5=A2=9E=E8=8B=B1=E6=96=87?= =?UTF-8?q?=E7=89=88=20README.en.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.en.md | 248 +++++++++++++++++++++++++++++++++++++++++++ README.md | 292 ++++++++++++++++++++++++++++----------------------- 2 files changed, 410 insertions(+), 130 deletions(-) create mode 100644 README.en.md diff --git a/README.en.md b/README.en.md new file mode 100644 index 0000000..6a45e3a --- /dev/null +++ b/README.en.md @@ -0,0 +1,248 @@ +[简体中文](README.md) | [English](README.en.md) + +# Seal (海豹) + +> django-base-templates — a Django development DEMO platform, supporting both non-separated (server-rendered) and separated (front-end / back-end) modes + +![Version](https://img.shields.io/badge/release-0.3-blue.svg) +![Language](https://img.shields.io/badge/language-python3.6-blue.svg) +![Env](https://img.shields.io/badge/env-django2.2-red.svg) +![Bootstrap3](https://img.shields.io/badge/model-bootstrap3-mauve.svg) +![RESTful](https://img.shields.io/badge/api-RESTful-blue.svg) +![GraphQL](https://img.shields.io/badge/api-GraphQL-blue.svg) + +> The project started on March 1st, which is International Seal Day, hence the name "Seal" (海豹). + +## Introduction + +Seal is a Django base development platform template built with the MVC pattern. It supports both **non-separated** development (Django template rendering) and **separated** development (RESTful / GraphQL APIs), so you can use it as a reference when building your own Django projects. + +It is based on Django 2.2 + Python 3.6 + Celery 4 for async tasks, uses the Inspinia 2.7 front-end template (Bootstrap3), and is developed entirely with CBVs (Class-Based Views). It also ships with DRF RESTful API examples, GraphQL examples, Kubernetes management, and SQL audit/execution modules as real-world references. + +Beyond being a base template, the project includes two complete ops-oriented implementations: a **K8s web console** (Node / Service / Pod lists + Pod WebSSH, executing commands via the Kubernetes API) and a **SQL audit & execution engine** (goInception / soar). + +The author develops and updates this project on weekends. + +## ✨ Features + +- **Base development templates**: `base` web layout template + `system` platform pages (home / login / password change), front-end template Inspinia 2.7 (Bootstrap3) +- **Asset management example**: the `assets` app provides a complete CRUD (CBV) example to reference when developing your own modules +- **RESTful API**: DRF-based API examples with Token authentication (`/api/token`), plus two built-in API docs endpoints (`/api/docs/` and Swagger-style `/api/docs2/`) +- **GraphQL**: graphene-django Query / Mutation examples (user list, single query, create/update/delete) with a built-in GraphiQL playground (`/graphql/`) +- **Kubernetes management**: Node / Service / Pod lists and Pod details, plus **Pod WebSSH** (django-channels + WebSocket, executing commands inside Pods via the Kubernetes API) +- **SQL audit & execution**: goInception for SQL checking / execution (with backup support) and soar for SQL optimization advice; supports multiple database environments +- **Two async task options**: Celery (recommended for scheduled tasks, with django-celery-beat / django-celery-results / flower) and dramatiq (ordinary async tasks) +- **Permission control**: login authentication + Django Permission-based page-level checks; the Django admin is prettified with django-simpleui + +## Roadmap + +* Phase 1: base templates (done) +* Phase 2: Kubernetes management platform (in progress) + * node/service/pod lists (done) + * pod webssh (done, executing commands via the Kubernetes API) +* Phase 3: MySQL SQL statement audit (done) + * SQL check and execution +* Phase 4: in progress — rebuilding the front end + +## 🛠 Tech Stack + +**Backend** + +- Python 3.6 / Django 2.2.4 (CBV style) +- Django REST framework 3.9.2 + django-rest-swagger (API and docs) +- graphene-django 2.2.0 (GraphQL) +- celery 4.1.1 + django-celery-beat + django-celery-results + flower; dramatiq 1.5.0 (async tasks) +- django-channels 2.2.0 + channels-redis (WebSocket channel for Pod WebSSH) +- kubernetes 9.0.0 (official Kubernetes Python client), PyMySQL / mysqlclient, paramiko, psutil + +**Front-end** + +- Bootstrap3 + Inspinia 2.7 template (non-separated mode) +- Vue-based front ends: and + +**Storage & services** + +- MySQL 5.7 / SQLite +- Redis (broker and backend for celery / dramatiq / channels) + +**SQL audit tools** + +- goInception / soar (executables are bundled in the repo under `sql/bin/`) + +## 🚀 Quick Start + +Requirements: Python 3.6, MySQL 5.7 (or SQLite), Redis. + +```bash +yum install python-devel mysql-devel python36-devel.x86_64 -y + +git clone https://github.com/hequan2017/seal +cd seal + +## Django 2.2 does not support older versions of SQLite. If you want to use +## SQLite for storage, please upgrade it following this blog post: +## https://www.jianshu.com/p/cdacf4b74646 + +python36 -m pip install -r requirements.txt +python36 manage.py makemigrations +python36 manage.py migrate +python36 manage.py createsuperuser + +python36 manage.py runserver 0.0.0.0:8001 + +// Run in the background +// nohup python36 manage.py runserver 0.0.0.0:8001 >> /tmp/http.log 2>&1 & +``` + +### K8s Module + +Edit the K8s settings in `seal/settings.py` (see `k8s/k8sApi/获取k8s admin token的方法.md` for how to get the admin token): + +```python +## K8S +Token = "" +APISERVER = 'https://192.168.100.111:6443' +``` + +### SQL Module + +Enter the project directory `cd seal`. The backup server can be configured in `sql/bin/config/config.toml`; for details, search for goInception on GitHub: + +```bash +chmod +x sql/bin/soar +chmod +x sql/bin/goInception + +./sql/bin/goInception -config=sql/bin/config/config.toml +``` + +### Async Tasks + +* Async option 1: Celery is recommended for scheduled tasks + +```bash +cd seal +celery -B -A seal worker -l info +``` + +* Async option 2: dramatiq for ordinary async tasks + +```bash +cd system/decorator/asynchronous/ +dramatiq asynchronous --watch . --log-file /tmp/dramatiq.log +``` + +### Notes + +* If you plan to use this in production, regenerate the SECRET_KEY in the settings file. +* Timezone: timezone support is enabled, so Django stores UTC times in the database and converts them to UTC+8 when you read them through the timezone API; Celery recognizes the timezone automatically. + +```python +from django.utils import timezone +for i in Users.objects.all(): + print(i.last_login) ## Reading the field directly returns a UTC time; handle it carefully if needed + print(timezone.localtime(i.last_login).strftime("%Y-%m-%d %H:%M:%S")) ## Format into local time + +## 2019-03-05 06:41:18.040809+00:00 +## 2019-03-05 14:41:18 +``` + +## 📁 Directory Structure + +``` +seal/ +├── assets/ # Asset management (CRUD example) +├── k8s/ # Kubernetes management (node/service/pod lists, pod detail, webssh) +├── sql/ # SQL audit & execution (goInception / soar; executables in bin/) +├── system/ # System module (login / users / password / async task examples) +├── document/ # Demo screenshots, SQL notes, coding standards +├── templates/ # Page templates (base/system/assets/k8s/sql) +├── static/ # Static assets (inspinia, ace, echarts, ueditor, etc.) +└── seal/ # Project configuration (settings / urls / schema / routing / celery) +``` + +## 📸 DEMO / Screenshots + +> Demo: + +> Account: admin　Password: 1qaz.2wsx + +> API docs: + +![List](document/demo/1.jpg) +![Create](document/demo/2.jpg) +![API](document/demo/3.jpg) +![API](document/demo/4.jpg) +![API](document/demo/5.jpg) +![K8S](document/demo/6.jpg) +![K8S](document/demo/7.jpg) +![SQL](document/demo/8.jpg) + +## 🔗 Related Projects + +* **seal-vue**: Vue-based front end (in active development): +* **seal-d2-admin**: Phase 4 front-end rebuild (D2Admin): + +## GraphQL Examples + +See `seal/schema.py` for the code. Endpoint: + +GraphQL request examples: + +``` +query{ + users{ + id, + username, + email + } +} + +query{ + singleUser(pk: 1){ + username, + email + } +} + +mutation createUser { + createUser (username: "test1") { + info { + id, + }, + ok + } +} + +mutation updateUser { + updateUser (pk:2,username: "test2") { + info { + id, + }, + ok + } +} + +mutation deleteUser { + deleteUser (pk:2) { + ok + } +} +``` + +## 📄 License + +[MIT](LICENSE) © 2019 He Quan (何全) + +## Support / Resources + +* CBV documentation: +* GraphQL reference (Chinese): + +### Community + +* For questions, join the QQ group: 620176501 django开发讨论群 +* Feature requests, feedback, and contributions are welcome. + +### Author + +* 何全 (He Quan) diff --git a/README.md b/README.md index 816e979..97a012f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,9 @@ -# 海豹 +[简体中文](README.md) | [English](README.en.md) + +# 海豹 seal + +> django-base-templates —— 主要为 Django 开发 DEMO，支持非前后端分离和前后端分离模式 + ![版本](https://img.shields.io/badge/release-0.3-blue.svg) ![语言](https://img.shields.io/badge/language-python3.6-blue.svg) ![语言](https://img.shields.io/badge/env-django2.2-red.svg) @@ -6,50 +11,161 @@ ![RESTful](https://img.shields.io/badge/api-RESTful-blue.svg) ![GraphQL](https://img.shields.io/badge/api-GraphQL-blue.svg) -> django-base-templates +> 因本项目开始时间为 3 月 1 日，是国际海豹日，故项目起名为 海豹 seal。 -> 因本项目开始时间为3月1日,是 国际海豹日,故项目起名为 海豹 seal +## 项目介绍 -> 主要为 django 基础开发平台, MVC 模式 开发.支持 非前后端分离 和 前后端分离模式,可以拿来参考 开发 django项目 +海豹（seal）是一个 Django 基础开发平台模板，采用 MVC 模式开发，同时支持 **非前后端分离**（Django 模板渲染）和 **前后端分离**（RESTful / GraphQL API）两种开发方式，可以直接拿来参考开发自己的 Django 项目。 -> 支持 RESTful 和 GraphQL +项目基于 Django 2.2 + Python 3.6 + Celery 4 异步任务，前端模板使用 inspinia 2.7（Bootstrap3），全部采用 CBV（Class-Based View）方式开发，并附带 DRF RESTful API 示例、GraphQL 示例、Kubernetes 管理和 SQL 审核执行等实战模块。 -> 作者会在周末进行开发、更新。 +除了作为基础模板，项目还内置了两个运维场景的完整实现：**K8s Web Console**（Node / Service / Pod 列表 + Pod WebSSH，通过调用 k8s api 执行命令）和 **SQL 审核执行引擎**（goInception / soar）。 -> 支持 k8s webssh 管理 pod！ sql执行 ！ +作者会在周末进行开发、更新。 - -## 介绍 -* 基于bootstrap3+django2.2 + python3.6+celery4 异步任务 -* 前端模板 inspinia 2.7 -* 采用cbv开发方式 -* drf RESTful api 例子 -* 前端 Vue版本 -* GraphQL -* k8s管理 -* sql执行 引擎 goInception / soar +## ✨ 功能特性 +- **基础开发模板**：base 网页基本模板 + system 平台基本网页（首页 / 登录 / 修改密码），前端模板 inspinia 2.7（Bootstrap3） +- **资产管理示例**：assets 模块提供完整的增删改查（CBV）范例，可作业务模块开发参考 +- **RESTful API**：基于 DRF 的接口示例，支持 Token 认证（`/api/token`），自带两套 API 文档（`/api/docs/` 与 Swagger 风格的 `/api/docs2/`） +- **GraphQL**：基于 graphene-django 的 Query / Mutation 示例（用户列表、单查、增删改），内置 GraphiQL 调试页面（`/graphql/`） +- **K8s 管理**：Node / Service / Pod 列表、Pod 详情，**Pod WebSSH**（django-channels + WebSocket，通过调用 k8s api 在 Pod 内执行命令） +- **SQL 审核执行**：集成 goInception 做 SQL 检测 / 执行（支持备份），集成 soar 输出语法优化建议，支持多环境数据库配置 +- **异步任务双方案**：Celery（推荐用于定时任务，配合 django-celery-beat / django-celery-results / flower）与 dramatiq（普通异步任务） +- **权限控制**：登录认证 + Django Permission 页面级权限校验，后台管理使用 django-simpleui 美化 ## 开发计划 -* 一期: 基础模板 (已完成) -* 二期: k8s管理平台 (开发中) - * node/service/pod 列表 (已完成) - * pod webssh (已完成， 通过调用 k8s api 进行执行命令) -* 三期: mysql sql语句审核(已完成) - * sql检测执行 -* 四期:正在开发中 　重构前端　https://github.com/hequan2017/seal-d2-admin - - -## DEMO +* 一期：基础模板（已完成） +* 二期：k8s 管理平台（开发中） + * node/service/pod 列表（已完成） + * pod webssh（已完成，通过调用 k8s api 进行执行命令） +* 三期：mysql sql 语句审核（已完成） + * sql 检测执行 +* 四期：正在开发中，重构前端 -> http://129.28.156.219:8001 +## 🛠 技术栈 -> 账户 admin 密码 1qaz.2wsx +**后端** -> api文档地址 : http://129.28.156.219:8001/api/docs/ +- Python 3.6 / Django 2.2.4（CBV 开发方式） +- Django REST framework 3.9.2 + django-rest-swagger（API 与文档） +- graphene-django 2.2.0（GraphQL） +- celery 4.1.1 + django-celery-beat + django-celery-results + flower；dramatiq 1.5.0（异步任务） +- django-channels 2.2.0 + channels-redis（Pod WebSSH 的 WebSocket 通道） +- kubernetes 9.0.0（官方 k8s python client）、PyMySQL / mysqlclient、paramiko、psutil -> vue 前端地址1 持续开发中 +**前端** + +- Bootstrap3 + inspinia 2.7 模板（非前后端分离模式） +- Vue 版本前端：、 + +**存储与依赖服务** + +- MySQL 5.7 / SQLite +- Redis（celery / dramatiq / channels 的 broker 与 backend） + +**SQL 审核工具** + +- goInception / soar（可执行文件已随仓库提供，位于 `sql/bin/`） + +## 🚀 快速开始 + +环境要求：Python 3.6、MySQL 5.7（或 SQLite）、Redis。 + +```bash +yum install python-devel mysql-devel python36-devel.x86_64 -y + +git clone https://github.com/hequan2017/seal +cd seal + +## django 2.2 不支持低版本的 sqlite，如果想使用 sqlite 存储数据， +## 请根据这个博客 https://www.jianshu.com/p/cdacf4b74646 进行升级 + +python36 -m pip install -r requirements.txt +python36 manage.py makemigrations +python36 manage.py migrate +python36 manage.py createsuperuser + +python36 manage.py runserver 0.0.0.0:8001 + +// 后台运行 +// nohup python36 manage.py runserver 0.0.0.0:8001 >> /tmp/http.log 2>&1 & +``` + +### K8s 模块 + +修改 `seal/settings.py` 中 k8s 相关设置（Token 获取方法见 `k8s/k8sApi/获取k8s admin token的方法.md`）： + +```python +## K8S +Token = "" +APISERVER = 'https://192.168.100.111:6443' +``` + +### SQL 模块 + +进入项目目录 `cd seal`，`sql/bin/config/config.toml` 里面可以设置备份服务器，详情可以 GitHub 搜索 goInception： + +```bash +chmod +x sql/bin/soar +chmod +x sql/bin/goInception + +./sql/bin/goInception -config=sql/bin/config/config.toml +``` + +### 异步任务 + +* 扩展功能-异步1：推荐定时任务用 celery + +```bash +cd seal +celery -B -A seal worker -l info +``` + +* 扩展功能-异步2：普通异步任务用 dramatiq + +```bash +cd system/decorator/asynchronous/ +dramatiq asynchronous --watch . --log-file /tmp/dramatiq.log +``` + +### 注意 + +* 如果想直接拿来做生产项目，请重新生成一个 settings 文件里面的 SECRET_KEY +* 时区问题（因为开启了时区，Django 在数据库里面保存的是 UTC 时间，调用的时候会帮你转为东八区，celery 会自动识别时间）： + +```python +from django.utils import timezone +for i in Users.objects.all(): + print(i.last_login) ## 直接读取时间，会是 utc 时间，未转换，如果需要处理请注意 + print(timezone.localtime(i.last_login).strftime("%Y-%m-%d %H:%M:%S")) ## 时间格式化为正常时间 + +## 2019-03-05 06:41:18.040809+00:00 +## 2019-03-05 14:41:18 +``` + +## 📁 目录结构 + +``` +seal/ +├── assets/ # 资产管理（增删改查示例） +├── k8s/ # K8s 管理（node/service/pod 列表、Pod 详情、webssh） +├── sql/ # SQL 审核执行（goInception / soar，bin 目录含可执行文件） +├── system/ # 系统模块（登录/用户/密码/异步任务示例） +├── document/ # demo 截图、sql 说明、代码规范 +├── templates/ # 页面模板（base/system/assets/k8s/sql） +├── static/ # 静态资源（inspinia、ace、echarts、ueditor 等） +└── seal/ # 项目配置（settings / urls / schema / routing / celery） +``` + +## 📸 DEMO / 截图 + +> DEMO： + +> 账户 admin　密码 1qaz.2wsx + +> API 文档地址： ![列表](document/demo/1.jpg) ![添加](document/demo/2.jpg) @@ -60,20 +176,17 @@ ![K8S](document/demo/7.jpg) ![SQL](document/demo/8.jpg) -## templates +## 🔗 相关项目 -* base 网页基本模板 -* system 平台基本网页(首页/登录/修改密码) -* assets 资产管理 (增删改查例子) -* document 代码规范 +* **seal-vue**：Vue 版本前端（持续开发中）： +* **seal-d2-admin**：四期重构前端（D2Admin）： +## GraphQL 使用示例 -## GraphQL -> 具体代码 请参考 seal/schema.py +具体代码请参考 `seal/schema.py`，请求地址： -> 请求地址 : +GraphQL 请求参数： -> GraphQL 请求参数 ``` query{ users{ @@ -115,101 +228,20 @@ mutation deleteUser { } ``` +## 📄 License -## 部署 -* mysql 5.7 / sqlite -* redis - -```bash -yum install python-devel mysql-devel python36-devel.x86_64 -y - -git clone https://github.com/hequan2017/seal -cd seal - -## django 2.2 不支持 低版本的 sqlite,如果想使用sqlite 存储数据 ，请根据这个博客 https://www.jianshu.com/p/cdacf4b74646 进行升级 - -python36 -m pip install -r requirements.txt -python36 manage.py makemigrations -python36 manage.py migrate -python36 manage.py createsuperuser - - -python36 manage.py runserver 0.0.0.0:8001 - -// -nohup python36 manage.py runserver 0.0.0.0:8001 >> /tmp/http.log 2>&1 & - - -``` - -## k8s模块 - -> 修改settings k8s 相关设置 -``` -## K8S -Token = "eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJrdWJlLXN5c3RlbSIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJkYXNoYm9hcmQtYWRtaW4tdG9rZW4tZGhobWMiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoiZGFzaGJvYXJkLWFkbWluIiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiOThkMDcwZWItODc1Yy0xMWU5LWE1MzgtMDAwYzI5N2I0ZmU3Iiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50Omt1YmUtc3lzdGVtOmRhc2hib2FyZC1hZG1pbiJ9.XDFpez2E84R_zlopt_uEHPvVGUtSavypyix6UcYJO3J4imHdJy7MEkfV-wltBA1H8x0TT2AW64rLlXaRJ8OkFWJ0myedfKdjnf7i0oLQ8j-7lw6rT3A0e2pKmpnOaBQfgzRm83-t2I5MMp3Iu9VNUiAbqQpjql4AKwRuJEEGCs99tKStUxzIsJKusmUHh9KAK4BAxySn9h16T2URZ7czLP4mty2crYWNV4KwSwFPthGhFPsl8mnet_hiV5k4me5a8frmXytOy64MmGW8w3TBgiM-7hBYSxt84QGGnyi84LU0EFgtLwBWEOTZeUKKQ6IkoAprMmNcSxX8WUJFlx_uJg" -APISERVER = 'https://192.168.100.111:6443' -``` - - -## SQL模块 - -> 进入项目 cd seal - -> sql/bin/config/config.toml 里面可以设置备份服务器，详情可以 github搜索 goInception -``` -chmod +x sql/bin/soar - -chmod +x sql/bin/goInception - -./sql/bin/goInception -config=sql/bin/config/config.toml -``` - - -## 异步任务 - - -* 扩展功能-异步1 推荐 定时任务用celery - -```bash - -cd seal -celery -B -A seal worker -l info -``` - -* 扩展功能-异步2 普通异步任务 用 dramatiq -```bash -cd system/decorator/asynchronous/ -dramatiq asynchronous --watch . --log-file /tmp/dramatiq.log - -``` - - -## 注意 -* 如果想直接拿来做生产项目,请重新生成一个 settings 文件里面的 SECRET_KEY -* 时区问题 -```python -##因为开启了时区,所以django在数据库里面保存的为 utc 时间, 调用的时候会帮你 转为 东八区, celery会自动识别时间 -from django.utils import timezone -for i in Users.objects.all(): - print(i.last_login) ## 直接读取时间,会是 utc时间,未转换, 如果需要处理 请注意 - print(timezone.localtime(i.last_login).strftime("%Y-%m-%d %H:%M:%S")) ## 时间格式化为 正常时间 - -## 2019-03-05 06:41:18.040809+00:00 -## 2019-03-05 14:41:18 - -``` - +[MIT](LICENSE) © 2019 何全 ## 售后服务 -* cbv 中文文档 -* GraphQL 中文参考文档 +* cbv 中文文档 +* GraphQL 中文参考文档 -### 其他 -* 有问题 可以加QQ群： 620176501 django开发讨论群 -* 欢迎提出你的需求和意见,或者来加入到本项目中一起开发。 +### 交流 + +* 有问题可以加 QQ 群：620176501 django开发讨论群 +* 欢迎提出你的需求和意见，或者来加入到本项目中一起开发。 ### 作者 -* 何全 +* 何全