Valar
valar for morghulis
Valar 是面向 Morghulis 前端的 Django 后端组件,提供模型与视图元数据、通用数据操作、账户和菜单管理,以及通过 WebSocket 返回结果和进度的后台任务。
安装与创建项目
需要 Python 3.10 或更高版本。建议在虚拟环境中安装:
python -m pip install valar
已有 Django 项目可以直接接入。新项目使用 Django 创建:
python -m django startproject myproject
cd myproject
下面以 myproject 为项目包名。依赖版本范围见 requirements.txt。
项目配置
1. settings.py
在现有配置中加入 Valar、Daphne、CORS 和 Channels,保留 Django 默认应用及业务应用。 Valar 必须排在 Daphne 和
django.contrib.staticfiles 前面,确保 Django 使用 Valar 的 runserver。
INSTALLED_APPS = [
'valar.apps.ValarConfig',
'daphne',
'corsheaders',
'channels',
# Django 默认应用和业务应用……
]
MIDDLEWARE = [
'corsheaders.middleware.CorsMiddleware',
# 原有中间件,包括 SessionMiddleware、CommonMiddleware 等……
'valar.system.middleware.ValarMiddleware',
]
ASGI_APPLICATION = 'myproject.asgi.application'
VALAR_HANDLER_MAPPING = 'myproject.urls.channel_mapping'
CHANNEL_LAYERS = {
'default': {
'BACKEND': 'channels.layers.InMemoryChannelLayer',
},
}
内存 channel layer 用于本地单进程开发。多个服务进程之间传递消息时,需要安装并配置共享的 channel layer 后端。
前后端跨域访问时,按实际前端地址配置允许的来源和请求头:
from corsheaders.defaults import default_headers
CORS_ALLOWED_ORIGINS = ['http://localhost:5173']
CORS_ALLOW_HEADERS = (*default_headers, 'client', 'auth')
2. urls.py
系统会自动挂载 /valar/,无需手动添加 Valar 路由。 在项目 URL 配置中保留业务路由:
from django.contrib import admin
from django.urls import path
urlpatterns = [
# 其他业务路由……
]
channel_mapping = {}
自动挂载在 ValarConfig.ready() 中执行,目标是 ROOT_URLCONF 指向的模块。该模块需要提供列表形式的 urlpatterns。使用
runserver、runserver --noreload 或直接通过 ASGI/WSGI 服务器启动时,都会执行路由挂载。
如果根路由中已经存在路径为 valar/ 的配置,系统会跳过添加。因此也支持显式配置:
from django.urls import include, path
urlpatterns = [
path('valar/', include('valar.urls')),
# 其他业务路由……
]
3. asgi.py
HTTP 路由由 Valar 自动挂载,WebSocket 路由需要在 ASGI 应用中配置。先初始化 Django,再导入消费者:
import os
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
from django.core.asgi import get_asgi_application
django_application = get_asgi_application()
from channels.routing import ProtocolTypeRouter, URLRouter
from django.urls import re_path
from valar.system.socket.consumer import ValarConsumer
application = ProtocolTypeRouter({
'http': django_application,
'websocket': URLRouter([
re_path(r'(?P<client>\w+)/$', ValarConsumer.as_asgi()),
]),
})
启动服务
日常启动只需执行:
python manage.py runserver
runserver 会自动生成并执行 valar 应用的迁移。首次接入项目或其他应用有待执行的迁移时,还需要运行 python manage.py migrate,以创建或更新 Django 自带应用和业务应用的数据表。
默认服务地址为 http://127.0.0.1:8000/,Valar HTTP 接口前缀为 /valar/。没有配置首页时,访问 / 返回 404。
Valar 的 runserver 继承 Daphne。Django 应用加载完成后,在服务开始监听前执行 Valar 数据库迁移和元数据重建,再启动 HTTP 与 WebSocket 服务。
路由挂载与数据初始化
两项启动行为分别执行:
| 行为 | 执行位置 | runserver | runserver --noreload | 直接启动 ASGI/WSGI |
|---|---|---|---|---|
自动挂载 /valar/ |
ValarConfig.ready() |
执行 | 执行 | 执行 |
| Valar 迁移和元数据重建 | runserver.inner_run() |
执行 | 执行 | 不执行 |
默认 runserver 开启自动重载,监控进程和服务进程都会初始化 Django。路由挂载逻辑会分别运行,但两个进程各自维护独立的
urlpatterns,不会在服务进程中添加两份路由。同一进程再次执行时,也会检查已有的 valar/ 路径并跳过。
需要关闭自动重载时使用:
python manage.py runserver --noreload
数据迁移与元数据刷新
每次 runserver 启动服务进程时,包括代码修改后的自动重载,都会:
- 为
valar应用生成并执行迁移。 - 删除并重新生成 Valar 自身实体的元数据。
- 重建字段工具和字段域配置。
初始化失败会中止服务启动。Valar 自身元数据的持久调整应写入模型或元数据定义,避免在下次启动时被重建覆盖。
业务应用的迁移需要自行生成和执行:
python manage.py makemigrations your_app
python manage.py migrate
WSGI 仅提供 HTTP 服务;使用 WebSocket 时需要按前面的示例配置并运行 ASGI 应用。
后台任务与 WebSocket
后台任务通过 HTTP 提交,Handler 在线程中运行,结果和进度通过 WebSocket 返回。
定义和注册 Handler
在 myproject/handlers.py 中定义接收 ChannelSender 的同步函数:
from valar.data.channel.ChannelSender import ChannelSender
def echo(sender: ChannelSender):
return {'message': sender.data.get('message', '')}
在 myproject/urls.py 中注册:
from .handlers import echo
channel_mapping = {
'echo': echo,
}
提交任务
先建立 WebSocket 连接:
ws://127.0.0.1:8000/browser_001/
路径中的 browser_001 是客户端标识,应与 HTTP 请求头中的 Client 一致。连接建立后,通过登录流程将连接绑定到账户,再提交任务:
POST /valar/channel/echo/request_001
Content-Type: application/json
Client: browser_001
Auth: 1
Authorization: Bearer <登录获得的 JWT>
{"data": {"message": "hello"}}
request_001 是用于关联任务回调的标识。HTTP 响应表示任务已提交,业务结果通过 WebSocket 返回,例如:
{
"__tag__": "channel",
"handler": "echo",
"token": "request_001",
"callback": "onResponse",
"data": {
"message": "hello"
}
}
回调类型如下:
| 回调 | 含义 |
|---|---|
onStart |
任务开始 |
onProceed |
进度更新 |
onResponse |
任务执行成功,返回结果 |
onError |
任务执行失败,返回错误信息 |
onStop |
任务结束 |
Handler 中调用 sender.tick(index, length) 设置进度,再调用 sender.process() 发送进度消息。
存在账户 ID 时,消息按账户发送。服务端可以通过 ValarSender().register(account_id, client) 绑定连接;客户端发送任意
WebSocket JSON 不会自动完成绑定。相关实现见 ChannelSender
和 ValarSender。
数据与元数据接口
以下路径均以 /valar/ 为前缀,不带尾部斜杠。<entity> 使用 应用标签.模型名,例如 valar.Account。
| 路径 | 功能 |
|---|---|
<entity>/insert_one、<entity>/save_one |
创建或保存单条数据 |
<entity>/fetch、<entity>/find_one、<entity>/find |
按 ID 或条件读取数据 |
<entity>/values、<entity>/search/<code> |
指定字段查询或分页查询 |
<entity>/delete_one、<entity>/sync_delete_many |
单条或批量删除 |
<entity>/sync_save_many、<entity>/sync_update_many |
批量保存或更新 |
<entity>/save_file、<entity>/remove_file |
上传或移除文件 |
metas、<entity>/<code>/meta_view |
模型和视图元数据 |
sign、register、load_user |
登录、注册与用户信息 |
load_menu、view_menu |
菜单读取 |
channel/<handler_name>/<token> |
提交后台任务 |
channel/batch/<entity>/<token> |
提交批量数据任务 |
JSON 接口通常使用以下响应结构,payload 为业务返回值:
{
"payload": true,
"message": null,
"code": "info"
}
各接口的请求体和认证行为不同,完整定义见 数据接口、元数据接口 和 账户接口。业务权限控制需结合具体接口实现。
扩展业务用户模型
业务模型可以继承 Valar 的抽象用户模型,关联 Valar 账户:
from django.db import models
from valar.models.auth import AbstractUser
class User(AbstractUser):
description = models.TextField(null=True, verbose_name='备注')
class Meta:
verbose_name = '用户'
该类继承 Valar 基础字段及账户关联。添加模型后,按常规 Django 流程为业务应用生成并执行迁移。
可选配置
| 功能 | 配置方式 |
|---|---|
| MySQL | 在项目包的 __init__.py 中调用 pymysql.install_as_MySQLdb(),并配置 DATABASES |
| MinIO 文件存储 | 配置 BASE_APP 和 VALAR_MINIO_URL,后者格式为 s3://<access_key>:<secret_key>@<host>:<port> |
| 邮件 | 配置 Django 邮件后端及 EMAIL_HOST_USER 等 SMTP 参数 |
本仓库开发
| 目录 | 内容 |
|---|---|
src/valar/ |
Valar 组件源码 |
valar_engine/ |
Django 示例项目及撮合服务 |
ems/ |
示例业务应用 |
tests/ |
自动化测试 |
仓库示例项目使用 src.valar.apps.ValarConfig 从源码加载组件;安装包接入使用 valar.apps.ValarConfig。
在仓库根目录安装依赖并启动:
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py runserver
验证开发服务器启动及 WebSocket 消息收发:
python -m unittest tests.test_websocket_startup -v
撮合服务的架构和使用方式见 MATCHING_ENGINE.md。
Metadata
Release files for valar 2.0.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| valar-2.0.10.tar.gz | 49.9 kB | Without provenance | Details for valar-2.0.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| valar-2.0.10-py3-none-any.whl | Python 3 | none | any | Details for valar-2.0.10-py3-none-any.whl |
Total release size: 96.5 kB
Release files / valar-2.0.10.tar.gz
| Download URL | valar-2.0.10.tar.gz |
|---|---|
| Size | 49.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69bffae7c208184d625cc5fc757a7b961c9f53d9097fd278c832c3fbf2e6a25c
|
|
BLAKE2b-256 checksum How to use checksums |
7f6effd5304621cb1e225835027deeeec26226070295f73adc456c0bd261e736
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Release files / valar-2.0.10-py3-none-any.whl
| Download URL | valar-2.0.10-py3-none-any.whl |
|---|---|
| Size | 46.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2c4b83f15ab9064b43d9b9f3d7a75ea7dce67a69d4ca5d05391053554113f37b
|
|
BLAKE2b-256 checksum How to use checksums |
b6ebe52834725a85883f2dbd82268a8ced77d8d388383bb4275f0cfbf1c158b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Security for valar 2.0.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.