add [meta check] command and fallback for help command, add resolve_domain function with default_dns_resolve_timeout in Preference, support serialize for manage=False django models (such as database view), remove base_url private restriction for OperationsAPI, add error handling for field rule generation, optimize @service.mount decorator

Author: voidZXL

docs/en/community/release.md

@@ -1,5 +1,27 @@
 # Release Note
 
+## v2.7.5
+
+Release Date:  2025/3/21
+
+### New features
+
+* ·Operations support `connection_key` to authorize the local and private services, and support connecting to private service directly after `connection_key` and `private_scope` are set.
+* Add `meta check` command to check if UtilMeta can load normally (no error)
+
+### Optimized
+
+* Optimized `orm.Field` to support lookup that has conflicted name with field name. 
+* Optimized runtime dispatch for all Adaptors (request, response, file, ...) with `__backends_package__` specified.
+* Optimized ResponseFile's file name recognition.
+* Optimized Session's `save` for database drivin session.
+* Optimized Filter's `query` to handle `@classmethod`.
+* orm support query and serialize `managed=False` Django model (such as the database view model without primary key)
+
+### Fixed
+
+* Fix Django route mounting problem (`__as__` method)
+
 ## v2.7.4
 
 Release Date:  2025/2/10

docs/en/guide/ops.md

@@ -233,7 +233,7 @@ The additional specified OpenAPI document will be integrated with the automatica
 ## Connect to UtilMeta Platform
 
 UtilMeta provides a platform for the observation and management operations of the API services: [UtilMeta Platform ](https://ops.utilmeta.com) you can enter the platform to connect and manage your UtilMeta service (or other services with supported frameworks), view API documents, data, logs and monitoring.
-### Connect Local Node
+### Connect Local API
 
 If you have configured the Operations successfully and run the local service, you can see the following prompt
 
@@ -253,7 +253,7 @@ meta connect
 You can see that the browser opened a window of UtilMeta platform, where you can see the APIs, Data tables, log and monitoring of your service.
 
 <img src="https://utilmeta.com/assets/image/connect-local-api.png" href="https://ops.utilmeta.com" target="_blank" width="800"/>
-### Connect Public service
+### Connect Public Service
 
 Connecting to the API service deployed online with public network address requires you to register an account on the UtilMeta platform. Because the management of online services requires a stricter authorization and authentication mechanism, you need to create a project team on the UtilMeta platform first. When you enter an empty project team, You can see the connection prompt for the UtilMeta platform
 
@@ -269,7 +269,7 @@ please visit [URL] to view and manage your APIs'
 
 Click the URL to access the online service you have connected in UtilMeta Platform, or click the **I’ve executed successfully** button in the platform to refresh after successful execution
 
-### Connect Intranet Cluster
+### Connect Intranet Cluster (by proxy)
 
 In addition to manage API services on the public network, we sometimes need to manage API services in private network clusters, such as internal services within the company's intranet, which do not have public IP addresses or access URLs. To manage these internal network services, we need to set up public network proxies in the internal network cluster, deploy a proxy service node for internal network penetration with authentication and service registration.
 
@@ -316,6 +316,60 @@ service.use(Operations(
 !!! note
 	UtilMeta services in the cluster should share the same Operations database as the proxy service, this database will serve as the service authentication basis and management storage center in the cluster. Current version mainly support PostgreSQL and MySQL as operations storage, futher releases will support other storage vendors.
 
+### Connect Private Service (directly)
+
+Beside the proxy mode in the above section, UtilMeta also provided a method to connect service node in the private network directly, similiar to connecting local API, with two conditions required:
+
+* Your management client (the computer that opened the UtilMeta Platform) must located at the **same private network** with the service you are going to manage. which means your computer can directly access the private service's API.
+* Your private service should provide HTTPS access (with SSL certificates)
+
+!!! note
+	 In the site that served with HTTPS (i.e. UtilMeta platform), browser will block all http requests (except for localhost), as you can see in the [Mixed Content | MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content), so to connect to the private service directly, you should use the HTTPS protocol
+
+After meeting the above conditions,  you need to add two additional configurations for Operations:
+
+* `connection_key`: In order to ensure the security of private network nodes, directly connecting to private network nodes requires you to pre-set a key (preferably a long random string) in the Operations configuration. UtilMeta will first verify this key for management requests from the private network, and only execute the corresponding request after verification is successful.
+* `private_scope`:  Authorize the permission range for private network requests. The value of the permission range can refer to the introduction in the `'local_scope'` section above. If you need to grant all permissions, you can use `['*']`
+
+The configuration example is as follows:
+```python
+from config.env import env
+from utilmeta.ops import Operations
+
+service.use(Operations(
+	base_url='https://my-private-service.com/api',   # replace with your domain
+	# other settings...
+	connection_key=env.CONNECTION_KEY,
+	private_scope=['*']
+))
+```
+
+Noted that `base_url` should also need to set to the address with HTTPS protocol and domain name.
+
+!!! note
+	Connect to private network service directly requres UtilMeta >= 2.7.5
+
+After the configuration, restart your service and you will see the OperationsAPI URL in the output
+
+```
+UtilMeta OperationsAPI loaded at https://my-private-service.com/api/ops
+```
+
+Then we can login to [UtilMeta Platform](https://ops.utilmeta.com), enter your project team, click the **\[Connect Local API\]** of  **\[+\]** button on the top bar
+
+<img src="https://utilmeta.com/assets/image/connect-local-hint.png" href="https://ops.utilmeta.com" target="_blank" width="300"/>
+
+Enter the OperationsAPI URL of your service in the prompted dialog, (for example: `https://my-private-service.com/api/ops`)
+
+<img src="https://utilmeta.com/assets/image/connect-local-api-form.png" href="https://ops.utilmeta.com" target="_blank" width="500"/>
+
+If you connected successfully, UtilMeta platform will prompt you to enter the `connection_key` you configured in the service, enter the correct key then you will be connected to your private service directly
+
+<img src="https://utilmeta.com/assets/image/set-connection-key-en.png" href="https://ops.utilmeta.com" target="_blank" width="500"/>
+
+!!! note
+	With "Save the key" checked, you can save the `connection_key` and OperationsAPI address of the private service to your project team, you won't need to enter these info again to connect to this service next time.
+
 ## Connect to Python project
 
 The operations system of UtilMeta framework can not only connect to the services made by UtilMeta framework, but also connect to the existing Python backend projects. The currently supported frameworks include

docs/zh/community/release.md

@@ -2,9 +2,12 @@
 
 ## v2.7.5
 
+发布时间：2025/3/21
+
 ### 新特性
 
 * ·Operations 系统支持配置 `connection_key` 对本地或内网的直连管理模式请求进行鉴权，配置 `connection_key` 与 `private_scope` 参数后可以在 UtilMeta 管理平台中直接管理与客户端位于同一内网的 UtilMeta 服务
+* 新增 `meta check` 命令用于检测 UtilMeta 服务是否加载正常（启动无错误）
 
 ### 优化项
 
@@ -13,6 +16,7 @@
 * 优化 File 文件对于 ResponseFile (HTTP 响应作为文件) 的文件名识别
 * 优化数据库驱动的 Session 的保存（`save`） 行为
 * 优化 Filter 组件的 `query` 查询函数对于 `@classmethod` 类方法的处理
+* orm 支持查询和序列化 `managed=False` 的 Django 模型（如没有主键的数据库视图） 
 
 ### 问题修复
 

docs/zh/guide/ops.md

@@ -326,10 +326,10 @@ service.use(Operations(
 除了上文的连接管理整个内网集群的 **代理模式** 外，UtilMeta 还提供了一种类似于连接本地节点的方式直接管理内网中的服务节点，这种直连内网服务管理需要满足两个条件：
 
 * 你的客户端（你打开 UtilMeta 管理平台的浏览器的电脑）与你要管理的 UtilMeta 服务位于同一 **内网**，也就是说你的电脑可以直接通过服务的内网地址直接访问到服务的 API 接口
-* 你的内网服务节点需要提供 HTTPS 协议的访问
+* 你的内网服务节点需要提供 HTTPS 协议的访问（需要配置 SSL 证书）
 
 !!! note
-	对 HTTPS 协议的要求是浏览器对每一个使用 HTTPS 协议服务的网页（UtilMeta 管理平台）所调用任何除了本机地址（localhost / 127.0.0.1）外的 URL 的要求，之后 UtilMeta 也规划上线桌面客户端或浏览器插件，可以绕过这个限制
+	对 HTTPS 协议的要求是浏览器对每一个使用 HTTPS 协议服务的网页（UtilMeta 管理平台）所调用任何除了本机地址（localhost / 127.0.0.1）外的 URL 的要求（参考文档：[Mixed Content | MDN](https://developer.mozilla.org/en-US/docs/Web/Security/Mixed_content)），之后 UtilMeta 也规划上线桌面客户端或浏览器插件，可以绕过这个限制
 
 满足以上条件后，直连内网节点需要你对 Operations 增加两项配置：
 
@@ -349,19 +349,32 @@ service.use(Operations(
 ))
 ```
 
+其中 `base_url` 也需要设置为使用 HTTPS 协议和域名的服务地址
+
 !!! note
 	使用直连内网节点的功能需要 UtilMeta 框架 2.7.5 及以上的版本
 
-配置完成后重启服务你会看到输出中有类似本地服务的
+配置完成后重启服务你会看到输出中包括 OperationsAPI 的地址
 
 ```
-UtilMeta OperationsAPI loaded at https://my-private-service.com/api/ops, connect your APIs at https://ops.utilmeta.com/localhost?local_node=https://my-private-service.com/api/ops
+UtilMeta OperationsAPI loaded at https://my-private-service.com/api/ops
 ```
 
-直接点击第二个链接即可进入 UtilMeta 平台连接你的内网节点，进入后会弹出一个对话框让你输入之前设置好的 `connection_key`，输入正确的密钥即可连接并管理内网节点
+之后我们进入 [UtilMeta 管理平台](https://ops.utilmeta.com)，进入你创建的团队中，点击顶栏中的【+】按钮中的【Connect Local API】连接内网服务
+
+<img src="https://utilmeta.com/assets/image/connect-local-hint.png" href="https://ops.utilmeta.com" target="_blank" width="300"/>
+
+在点击打开的对话框中输入服务的 OperationsAPI 地址（例如 `https://my-private-service.com/api/ops`）
+
+<img src="https://utilmeta.com/assets/image/connect-local-api-form.png" href="https://ops.utilmeta.com" target="_blank" width="500"/>
+
+连接成功后会提示你输入之前设置好的 `connection_key`，输入正确的密钥即可连接并管理内网节点
 
 <img src="https://utilmeta.com/assets/image/set-connection-key-en.png" href="https://ops.utilmeta.com" target="_blank" width="500"/>
 
+!!! note
+	勾选保存即可将 `connection_key` 与内网服务地址保存到这个项目团队中，后面再次连接就不需要重复输入了
+
 
 ## 连接现有 Python 项目
 

tests/server/api.py

@@ -412,3 +412,11 @@ def hello(self):
     @api.get
     def plus(self, a: int, b: int) -> int:
         return a + b
+
+    class fQuery(utype.Schema):
+        f: str
+
+    @api.get
+    def file(self, fq: fQuery = request.Query):
+        from utilmeta.core.file import File
+        return self.response(attachment=File(fq.f.encode(), filename='f.txt'))

tests/server/app/migrations/0001_initial.py

@@ -185,7 +185,7 @@ class Migration(migrations.Migration):
             model_name="basecontent",
             name="liked_bys",
             field=models.ManyToManyField(
-                db_table="like", related_name="likes", to="app.user"
+                db_table="liked", related_name="likes", to="app.user"
             ),
         ),
         migrations.AlterUniqueTogether(

tests/server/app/migrations/0003_statistics.py

@@ -0,0 +1,60 @@
+# Generated by Django 4.2.17 on 2025-03-19 03:13
+
+from django.db import migrations, models
+
+
+CREATE_SQL = """
+CREATE VIEW article_stats AS
+    SELECT
+        a.basecontent_ptr_id AS article_id,
+        COUNT(DISTINCT l.user_id) AS liked_bys_num,
+        COUNT(DISTINCT c.basecontent_ptr_id) AS comments_num
+    FROM
+        article a
+    INNER JOIN
+        content ct ON a.basecontent_ptr_id = ct.id
+    LEFT JOIN
+        liked l ON ct.id = l.basecontent_id
+    LEFT JOIN
+        comment c ON ct.id = c.on_content_id
+    GROUP BY
+        a.basecontent_ptr_id;
+"""
+
+DROP_SQL = "DROP VIEW article_stats;"
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("app", "0002_article_tags"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Statistics",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                ("date", models.DateField()),
+                ("articles_num", models.PositiveIntegerField(default=0)),
+                ("comments_num", models.PositiveIntegerField(default=0)),
+                ("users_num", models.PositiveIntegerField(default=0)),
+            ],
+            options={
+                "db_table": "stats",
+                "managed": False,
+            },
+        ),
+        migrations.RunSQL(
+            sql=CREATE_SQL,
+            reverse_sql=DROP_SQL,
+        ),
+    ]

tests/server/app/models.py

@@ -46,7 +46,7 @@ class BaseContent(AwaitableModel):
     created_at = models.DateTimeField(auto_now_add=True)
     updated_at = models.DateTimeField(auto_now=True)
     public = models.BooleanField(default=False)
-    liked_bys = models.ManyToManyField(User, related_name="likes", db_table="like")
+    liked_bys = models.ManyToManyField(User, related_name="likes", db_table="liked")
     author = models.ForeignKey(User, related_name="contents", on_delete=models.CASCADE)
     author_id: int
     type = models.CharField(max_length=20, default="article")
@@ -88,3 +88,13 @@ class Session(AbstractSession):
 
     class Meta:
         db_table = 'session'
+
+
+class ArticleStats(AwaitableModel):
+    article_id = models.PositiveIntegerField()
+    comments_num = models.PositiveIntegerField(default=0)
+    liked_bys_num = models.PositiveIntegerField(default=0)
+
+    class Meta:
+        db_table = "article_stats"
+        managed = False

tests/server/app/schema.py

@@ -1,13 +1,13 @@
 from utype.types import *
 from utilmeta.core import orm, auth
-from .models import User, Article, Comment, BaseContent
+from .models import User, Article, Comment, BaseContent, ArticleStats
 from utype import Field
 from utilmeta.core.orm.backends.django import expressions as exp
 from utilmeta.utils import awaitable
 from django.db import models
 
 
-__all__ = ["UserSchema", "ArticleSchema", "CommentSchema",
+__all__ = ["UserSchema", "ArticleSchema", "CommentSchema", "ArticleStatsSchema", "ArticleStatsQuery",
            "ContentSchema", 'UserBase', 'UserQuery', 'ArticleQuery', 'ArticleBase', 'ContentBase']
 
 
@@ -279,3 +279,16 @@ class ArticleQuery(orm.Query[Article]):
     offset: int = orm.Offset(alias='@offset')
     limit: int = orm.Limit(alias='@limit')
     scope: dict = orm.Scope()
+
+
+class ArticleStatsQuery(orm.Query[ArticleStats]):
+    article_id: int
+    comments_gte: int = orm.Filter(query=lambda x: models.Q(comments_num__gte=x))
+    liked_bys_gte: int = orm.Filter(query=lambda x: models.Q(liked_bys_num__gte=x))
+    sort: str = orm.OrderBy([ArticleStats.article_id, ArticleStats.liked_bys_num, ArticleStats.comments_num])
+
+
+class ArticleStatsSchema(orm.Schema[ArticleStats]):
+    article_id: int
+    comments_num: int
+    liked_bys_num: int

tests/test_1_orm/test_schema_query.py

@@ -115,6 +115,42 @@ def test_init_articles(self, service, db_using):
         assert content.id == 1
         assert content.article.id == 1
 
+    def test_unmanaged_view_model_query(self, service, db_using):
+        from app.schema import ArticleStatsSchema, ArticleStatsQuery
+        res1 = ArticleStatsSchema.serialize(
+            ArticleStatsQuery(comments_gte=2, sort='liked_bys_num'),
+            context=orm.QueryContext(using=db_using)
+        )
+        assert len(res1) == 2
+        assert res1[0].article_id == 4
+        assert res1[1].article_id == 1
+        assert res1[1].comments_num == 2
+        assert res1[1].liked_bys_num == 3
+        res = ArticleStatsSchema.init(
+            ArticleStatsQuery(article_id=1),
+            context=orm.QueryContext(using=db_using)
+        )
+        assert res.article_id == 1
+        assert res.comments_num == 2
+
+    @pytest.mark.asyncio
+    async def test_async_unmanaged_view_model_query(self, service, db_using):
+        await self.refresh_db(db_using)
+        from app.schema import ArticleStatsSchema, ArticleStatsQuery
+        res1 = await ArticleStatsSchema.aserialize(
+            ArticleStatsQuery(comments_gte=2, sort='liked_bys_num'), context=orm.QueryContext(using=db_using)
+        )
+        assert len(res1) == 2
+        assert res1[0].article_id == 4
+        assert res1[1].article_id == 1
+        assert res1[1].comments_num == 2
+        assert res1[1].liked_bys_num == 3
+        res = await ArticleStatsSchema.ainit(
+            ArticleStatsQuery(article_id=1), context=orm.QueryContext(using=db_using)
+        )
+        assert res.article_id == 1
+        assert res.comments_num == 2
+
     def test_orm_preferences(self, service):
         # orm_on_conflict_annotation
 
@@ -204,6 +240,7 @@ def test_queryset_generator(self, service, db_using):
 
     @pytest.mark.asyncio
     async def test_async_queryset_generator(self, service, db_using):
+        await self.refresh_db(db_using)
         from app.models import Article
         from app.schema import ArticleQuery
         from django.db import models