Skip to main content

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 启动服务进程时,包括代码修改后的自动重载,都会:

  1. 为 valar 应用生成并执行迁移。
  2. 删除并重新生成 Valar 自身实体的元数据。
  3. 重建字段工具和字段域配置。

初始化失败会中止服务启动。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)

Source distribution for valar 2.0.10
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)

Table of built distributions (wheels) for valar 2.0.10
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

2.0.10 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page