creat01deployengine 1.0.0__tar.gz → 1.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/.gitignore +8 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/AI_USAGE.md +12 -7
- creat01deployengine-1.0.1/PKG-INFO +164 -0
- creat01deployengine-1.0.1/README.md +148 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/pyproject.toml +1 -1
- creat01deployengine-1.0.1/src/creat01deployengine/logging/__init__.py +5 -0
- creat01deployengine-1.0.1/src/creat01deployengine/models/__init__.py +27 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/models/common.py +1 -1
- creat01deployengine-1.0.1/src/creat01deployengine/models/infrastructure.py +86 -0
- creat01deployengine-1.0.1/src/creat01deployengine/models/project_ssl.py +61 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/models/projects.py +7 -4
- creat01deployengine-1.0.1/src/creat01deployengine/models/users.py +38 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/__init__.py +6 -4
- creat01deployengine-1.0.1/src/creat01deployengine/resources/authentication.py +64 -0
- creat01deployengine-1.0.1/src/creat01deployengine/resources/certificates.py +32 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/load_balancers.py +10 -2
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/machines.py +14 -0
- creat01deployengine-1.0.1/src/creat01deployengine/resources/managed_registry.py +81 -0
- creat01deployengine-1.0.1/src/creat01deployengine/resources/projects.py +75 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/tracking.py +7 -12
- creat01deployengine-1.0.1/src/creat01deployengine/resources/users.py +48 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/workflows.py +1 -1
- creat01deployengine-1.0.1/src/creat01deployengine/tracking/__init__.py +5 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/tracking/client.py +23 -15
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/version.py +1 -1
- creat01deployengine-1.0.1/tests/test_client.py +178 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/tests/test_live_api.py +0 -1
- creat01deployengine-1.0.1/tests/test_models.py +24 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/tests/test_resource_contracts.py +155 -32
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/uv.lock +1 -1
- creat01deployengine-1.0.0/PKG-INFO +0 -81
- creat01deployengine-1.0.0/README.md +0 -65
- creat01deployengine-1.0.0/src/creat01deployengine/logging/__init__.py +0 -5
- creat01deployengine-1.0.0/src/creat01deployengine/models/__init__.py +0 -14
- creat01deployengine-1.0.0/src/creat01deployengine/models/infrastructure.py +0 -27
- creat01deployengine-1.0.0/src/creat01deployengine/resources/authentication.py +0 -38
- creat01deployengine-1.0.0/src/creat01deployengine/resources/certificates.py +0 -19
- creat01deployengine-1.0.0/src/creat01deployengine/resources/projects.py +0 -37
- creat01deployengine-1.0.0/src/creat01deployengine/resources/security_groups.py +0 -28
- creat01deployengine-1.0.0/src/creat01deployengine/tracking/__init__.py +0 -5
- creat01deployengine-1.0.0/tests/test_client.py +0 -94
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/LICENSE +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/__init__.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/client.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/errors.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/logging/reporter.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/py.typed +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/alerts.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/base.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/domains.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/feedback.py +0 -0
- {creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/resources/payments.py +0 -0
|
@@ -49,6 +49,7 @@ coverage.xml
|
|
|
49
49
|
*.py,cover
|
|
50
50
|
.hypothesis/
|
|
51
51
|
.pytest_cache/
|
|
52
|
+
.deepeval/
|
|
52
53
|
cover/
|
|
53
54
|
|
|
54
55
|
# Translations
|
|
@@ -205,10 +206,17 @@ pip_packages/
|
|
|
205
206
|
*.mp4
|
|
206
207
|
*.mp3
|
|
207
208
|
*.pem
|
|
209
|
+
deploy/managed-registry/certs/token-signing.key
|
|
208
210
|
local_settings.py
|
|
209
211
|
certs/
|
|
210
212
|
reference/
|
|
213
|
+
# Public reference articles are part of the shipped documentation.
|
|
214
|
+
!portal/src/content/docs/reference/
|
|
215
|
+
!portal/src/content/docs/reference/*.md
|
|
216
|
+
!portal/src/content/docs-en/reference/
|
|
217
|
+
!portal/src/content/docs-en/reference/*.md
|
|
211
218
|
*.bak
|
|
212
219
|
*.dat
|
|
213
220
|
*.dir
|
|
214
221
|
.dev/
|
|
222
|
+
.artifacts/
|
|
@@ -4,8 +4,8 @@ Use this decision order when generating code with `creat01deployengine`.
|
|
|
4
4
|
|
|
5
5
|
1. For management operations, read `DEPLOYENGINE_API_KEY` from the server
|
|
6
6
|
environment and create `DeployEngine` or `AsyncDeployEngine`.
|
|
7
|
-
2.
|
|
8
|
-
|
|
7
|
+
2. Use the tracking resource or `Tracker` only in trusted server code, with
|
|
8
|
+
the user API Key and project name. Never place the key in browser code.
|
|
9
9
|
3. Prefer named resource methods over raw `client.request`.
|
|
10
10
|
4. For writes, provide an idempotency key when the method accepts one. Never
|
|
11
11
|
retry a payment, deployment, DNS, or infrastructure write blindly.
|
|
@@ -29,15 +29,16 @@ DNS records -> domains.records/create_record/update_re
|
|
|
29
29
|
sync load balancer -> load_balancers.sync
|
|
30
30
|
bind project to load balancer -> load_balancers.bind_project
|
|
31
31
|
add load-balancer listener -> load_balancers.add_listener
|
|
32
|
-
apply host firewall -> security_groups.apply
|
|
33
|
-
add firewall rule -> security_groups.add_rule
|
|
34
32
|
send alert -> alerts.send
|
|
35
33
|
create payment -> payments.create_order
|
|
36
34
|
refund payment -> payments.refund
|
|
37
|
-
send end-user
|
|
38
|
-
login with
|
|
35
|
+
send end-user registration code -> authentication.send_registration_code
|
|
36
|
+
register/login with password -> authentication.register/password_login
|
|
37
|
+
recover/change/refresh end-user auth -> authentication.forgot_password/reset_password/change_password/refresh_token
|
|
39
38
|
create customer feedback link -> feedback.create_ticket_link
|
|
40
|
-
|
|
39
|
+
list/create platform users -> users.list/create
|
|
40
|
+
change role/delete platform user -> users.change_role/delete
|
|
41
|
+
tracking analytics/identity -> client.tracking.collect/identify or Tracker.track/identify
|
|
41
42
|
send application log -> LogReporter.debug/info/warning/error
|
|
42
43
|
```
|
|
43
44
|
|
|
@@ -62,7 +63,11 @@ async def deploy(project_id: int, body: dict) -> None:
|
|
|
62
63
|
raise
|
|
63
64
|
```
|
|
64
65
|
|
|
66
|
+
Tracking ingestion uses the existing `business` or `full_access` API Key scope.
|
|
65
67
|
Scopes: `read`, `deploy`, `machines`, `databases`, `certificates`,
|
|
66
68
|
`monitoring`, `infrastructure`, and `business`. A 403 means the key needs the
|
|
67
69
|
scope documented on the resource; do not work around it with a broader key in
|
|
68
70
|
client code.
|
|
71
|
+
|
|
72
|
+
User management is administrator-only. Its write methods require an
|
|
73
|
+
administrator Bearer JWT; do not attempt them with a management API key.
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: creat01deployengine
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Official Python SDK for Creat01 DeployEngine
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Typing :: Typed
|
|
10
|
+
Requires-Python: >=3.9
|
|
11
|
+
Requires-Dist: httpx<1,>=0.27
|
|
12
|
+
Provides-Extra: test
|
|
13
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
14
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# creat01deployengine Python SDK
|
|
18
|
+
|
|
19
|
+
Release **1.0.1** follows the repository's sequential version policy. It changes the tracking and project authentication contracts from public 1.0.0; read the [migration guide](https://jihulab.com/creat01-group1/deployengine/-/blob/main/client/MIGRATION.md) before upgrading. Version increments do not imply backward compatibility.
|
|
20
|
+
|
|
21
|
+
机器 Nginx 站点列表与正文返回 `readOnly`、`projectBindings`,公开类型为 `NginxConfigInfo`、`NginxConfigContent` 和 `NginxProjectBinding`。项目相关站点在通用机器配置 API 中仅可读取,编辑、重命名/创建覆盖、启停及批量删除均返回 409/ConflictError,需转到项目接口操作。Python/TypeScript SDK 均没有专用 Nginx 资源域,沿用通用 request 调用,不新增业务方法;两端同步公开类型和 OpenAPI 契约。 原文件与同名启用入口联合判定;即使原文件独立,只要启用入口的软链、硬链或标记副本关联项目,readOnly 也为 true,通用写请求返回 409。
|
|
22
|
+
|
|
23
|
+
Official synchronous and asynchronous clients for the DeployEngine API.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python -m pip install creat01deployengine
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Use `DeployEngine` in synchronous code, `AsyncDeployEngine` in asyncio code,
|
|
30
|
+
and `Tracker`/`LogReporter` for application-side event ingestion. Never ship a
|
|
31
|
+
management API key in browser, desktop, or mobile code.
|
|
32
|
+
|
|
33
|
+
## Managed private Registry
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
client.managed_registry.set_namespace("alice-space") # Globally unique; existing images and references are migrated.
|
|
37
|
+
repositories = client.managed_registry.repositories()
|
|
38
|
+
references = client.managed_registry.references("alice-space/team/api")
|
|
39
|
+
subscriptions = client.managed_registry.image_auto_updates()
|
|
40
|
+
client.managed_registry.delete_repository("alice-space/team/obsolete") # Deletes every tag and manifest when unreferenced.
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
托管 Registry 支持项目镜像自动更新订阅。
|
|
45
|
+
|
|
46
|
+
镜像部署前可调用 `client.managed_registry.connect_image_registry()` 建立 pull-only 镜像连接。
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
connection = client.managed_registry.connect_image_registry()
|
|
50
|
+
client.projects.save_image_auto_update(42, connection["id"], "alice-space/team/api", tag="latest")
|
|
51
|
+
# Pause/resume without losing the saved tag or update policy.
|
|
52
|
+
saved = client.projects.image_auto_update(42)
|
|
53
|
+
client.projects.save_image_auto_update(
|
|
54
|
+
42, saved["registry_id"], saved["repository"], tag=saved["tag"],
|
|
55
|
+
enabled=False, update_mode=saved["update_mode"],
|
|
56
|
+
ignore_platform_builds=saved["ignore_platform_builds"],
|
|
57
|
+
) # Use enabled=True with the same saved fields to resume.
|
|
58
|
+
# Permanently remove the subscription configuration.
|
|
59
|
+
client.projects.delete_image_auto_update(42)
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Docker login accepts either the DeployEngine account username/password or a separate Registry credential. Create, list, rotate, and revoke separate credentials with `client.managed_registry`; the secret is returned only on creation or rotation, never expires automatically, and remains valid until revoked or rotated. Both user credential types are restricted to the caller's namespace. The SDK returns the one-time secret to the caller and does not store it. The platform generates separate short-lived internal credentials for unattended builds and deployments. Portal JWTs and management API keys are not Docker credentials.
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import os
|
|
67
|
+
from creat01deployengine import DeployEngine
|
|
68
|
+
from creat01deployengine.errors import PermissionDeniedError
|
|
69
|
+
|
|
70
|
+
try:
|
|
71
|
+
with DeployEngine(
|
|
72
|
+
api_key=os.environ["DEPLOYENGINE_API_KEY"],
|
|
73
|
+
base_url="https://deployengine.creat01.com",
|
|
74
|
+
) as client:
|
|
75
|
+
projects = client.projects.list(page=1, pageSize=20)
|
|
76
|
+
machine = client.machines.get(12)
|
|
77
|
+
except PermissionDeniedError as exc:
|
|
78
|
+
print(f"missing API scope; request={exc.request_id}")
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
from creat01deployengine import AsyncDeployEngine
|
|
83
|
+
|
|
84
|
+
async with AsyncDeployEngine(api_key=key) as client:
|
|
85
|
+
projects = await client.projects.list()
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Resource map
|
|
89
|
+
|
|
90
|
+
| Attribute | Purpose | Typical scope |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `projects` | CRUD, precheck, deployments, releases, deploy/restart streams | `read`, `deploy` |
|
|
93
|
+
| `machines` | CRUD, recommendations, Agent state, port checks | `machines` |
|
|
94
|
+
| `workflows` | Task progress, detail, termination | `read`, `deploy` |
|
|
95
|
+
| `certificates` | CRUD, upload, manual/automatic Let's Encrypt renewal, deployment | `certificates` |
|
|
96
|
+
| `domains` | Domain CRUD and DNS records | `read` |
|
|
97
|
+
| `load_balancers` | Gateway config, sync, bindings, listeners | `infrastructure` |
|
|
98
|
+
| `alerts` | Alert contacts and notification sending | `monitoring` |
|
|
99
|
+
| `payments` | Payment orders and refunds | `business` |
|
|
100
|
+
| `authentication` | Project account/password registration, login, recovery and sessions; SMS/email code requests take an owner-scoped `credential_id` per call | public `projectId` / end-user bearer token |
|
|
101
|
+
| `feedback` | Customer feedback ticket links | `business` |
|
|
102
|
+
| `tracking` | Project event ingestion | `business` API Key scope |
|
|
103
|
+
| `users` | Admin-only user list/create/role/deletion | administrator role; JWT for writes |
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
with DeployEngine(access_token=admin_jwt) as admin:
|
|
107
|
+
page = admin.users.list(page=1, page_size=20, role="user", keyword="ops")
|
|
108
|
+
created = admin.users.create({"username": "operator", "password": "secret123"})
|
|
109
|
+
admin.users.change_role(created["id"], "admin")
|
|
110
|
+
admin.users.delete(created["id"])
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
User-management writes require an administrator Bearer JWT; the list also
|
|
114
|
+
accepts an administrator API key. Authenticated non-admin users receive
|
|
115
|
+
`PermissionDeniedError`. Business-capability management is likewise admin-only,
|
|
116
|
+
while login, callback, and one-time feedback endpoints keep
|
|
117
|
+
their project credential, signature, or token authentication. Project tracking
|
|
118
|
+
uses the API Key and project name supplied to the tracking resource.
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
with DeployEngine(api_key=key) as client:
|
|
122
|
+
for event in client.projects.deploy_stream(7, {"branch": "main"}):
|
|
123
|
+
print(event)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Resources return the unwrapped `data` field. Writes are not retried unless an
|
|
127
|
+
idempotency key is present. `DeployEngineError` exposes `status_code`, `code`,
|
|
128
|
+
`request_id`, `details`, and `retryable`. See `AI_USAGE.md` for task recipes.
|
|
129
|
+
|
|
130
|
+
Machine metrics start automatically after machine creation and Agent
|
|
131
|
+
connection, at a system-owned one-minute interval. This SDK does not currently
|
|
132
|
+
expose the `/api/monitor/machines` HTTP resource; `alerts` manages alert
|
|
133
|
+
contacts only. Existing direct HTTP integrations should move threshold/contact
|
|
134
|
+
updates to `PUT /api/monitor/machines/{machine_id}/alert-config`; legacy monitor
|
|
135
|
+
add, remove, and interval endpoints remain compatibility-only.
|
|
136
|
+
|
|
137
|
+
Maintainers can run the opt-in live smoke test with
|
|
138
|
+
`DEPLOYENGINE_E2E_API_KEY=... pytest tests/test_live_api.py`. It performs only
|
|
139
|
+
authenticated list operations and does not deploy or mutate resources.
|
|
140
|
+
|
|
141
|
+
证书续期:`client.certificates.renew(cert_id)` 会触发已有部署机器的证书更新及 Nginx 重载;任一机器失败时返回错误,需检查对应部署记录。
|
|
142
|
+
|
|
143
|
+
## Load balancer sync
|
|
144
|
+
|
|
145
|
+
`client.load_balancers.sync(id)` synchronizes bound project gateway configuration. HTTP 200 is not proof of application: check `sync_status`, `last_sync_error`, `config_revision`, and `applied_revision` in the returned data. Independent listener records (even disabled ones) are metadata only and make sync fail before remote operations. Configure domains and certificates on the project instead; remove independent listener metadata before retrying. Removing metadata does not remove project sites. New or changed configurations remain `pending` until sync succeeds for the current revision; old `ready` records should be resynced. Methods, paths and response envelopes remain compatible; this corrects false success reporting.
|
|
146
|
+
|
|
147
|
+
机器证书部署查询:Python `client.certificates.machine_deployments(machine_id)`,TypeScript `client.api.certificates.machineDeployments(machineId)` 调用 `GET /api/certificates/machines/{machine_id}/deployments`,返回 `{ list: [...] }`。仅返回当前用户所拥有机器的部署元数据与证书名称/域名,不包含 PEM 或私钥内容;不可见或不存在的机器返回 HTTP 404。该能力为兼容性新增。
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
### 项目 SSL 证书
|
|
151
|
+
|
|
152
|
+
项目域名发布默认要求 HTTPS,必须先确认每个域名的证书绑定并部署到入口机器;无证书时不会静默降级。需要 HTTP 时显式保存 `mode: "http"`。旧客户端请求字段保持兼容,但未准备证书的域名发布现在返回就绪错误;运行中的服务不会因升级自动改配置。证书申请继续使用独立证书工作流。
|
|
153
|
+
|
|
154
|
+
Python:`client.api.projects.ssl(id, check_remote=True)`、`save_ssl(id, {"mode": "https", "bindings": {"app.example.com": certificate_id}})`、`deploy_ssl(id, "app.example.com")`、`preview_ssl(id)`、`apply_ssl(id, preview["revision"])`。TypeScript 对应 `ssl(id, true)`、`saveSsl`、`deploySsl`、`previewSsl`、`applySsl`。查询可传 `host` 准备待新增域名。类型为 `ProjectSslPolicy`、`ProjectSslStatus`、`ProjectSslPreview`。保存绑定只修改期望配置,应用前必须审阅预览的站点替换内容;409 表示未就绪、操作冲突或需要重新预览。返回元数据不含证书/私钥正文。应用只核对入口本机 TLS;公网 DNS、CDN、防火墙需单独验证。
|
|
155
|
+
|
|
156
|
+
工作流 `GET /api/workflow-tasks/{task_id}/progress` 的 `logPreview` 为最多 12,000 字符的日志尾部;完整保留日志使用 `/detail` 的 `logContent`。接口路径、字段与认证保持兼容。 零停机清理恢复及按次诊断语义见 [SDK 说明](../../docs/sdk.md)。
|
|
157
|
+
|
|
158
|
+
### 系统自动识别与容器盘点
|
|
159
|
+
|
|
160
|
+
机器创建/修改连接信息自动保存系统版本和架构;读取 `platform` 与 `platformProbeAt`,无需手动填写系统。Python 使用 `client.machines.container_inventory(machine_id=7)`,TypeScript 使用 `client.api.machines.containerInventory(7)`;省略机器 ID 查询本人全部机器。`machines[]` 包含采集时间、ready/unavailable、errorCode 与容器列表,局部失败必须单独处理。容器的 `readOnly` 与 `projectBindings` 指示项目生命周期归属;项目容器只读,通用写操作(包括强制删除)返回 409,须通过项目流程管理。大规模盘点最长 90 秒,请将客户端 timeout 配置为 120 秒。容器操作使用机器 ID 与完整容器 ID;409 表示操作未完成,先刷新确认再重试。详见[SDK 说明](../../docs/sdk.md)。
|
|
161
|
+
|
|
162
|
+
### 部署失败诊断与日志兼容性
|
|
163
|
+
|
|
164
|
+
部署失败事件的 `content` 可包含容器状态与启动日志;失败或清理后可用通用 request 查询原项目日志接口。现有方法、字段和认证保持兼容;详见[SDK 说明](../../docs/sdk.md)。
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# creat01deployengine Python SDK
|
|
2
|
+
|
|
3
|
+
Release **1.0.1** follows the repository's sequential version policy. It changes the tracking and project authentication contracts from public 1.0.0; read the [migration guide](https://jihulab.com/creat01-group1/deployengine/-/blob/main/client/MIGRATION.md) before upgrading. Version increments do not imply backward compatibility.
|
|
4
|
+
|
|
5
|
+
机器 Nginx 站点列表与正文返回 `readOnly`、`projectBindings`,公开类型为 `NginxConfigInfo`、`NginxConfigContent` 和 `NginxProjectBinding`。项目相关站点在通用机器配置 API 中仅可读取,编辑、重命名/创建覆盖、启停及批量删除均返回 409/ConflictError,需转到项目接口操作。Python/TypeScript SDK 均没有专用 Nginx 资源域,沿用通用 request 调用,不新增业务方法;两端同步公开类型和 OpenAPI 契约。 原文件与同名启用入口联合判定;即使原文件独立,只要启用入口的软链、硬链或标记副本关联项目,readOnly 也为 true,通用写请求返回 409。
|
|
6
|
+
|
|
7
|
+
Official synchronous and asynchronous clients for the DeployEngine API.
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
python -m pip install creat01deployengine
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Use `DeployEngine` in synchronous code, `AsyncDeployEngine` in asyncio code,
|
|
14
|
+
and `Tracker`/`LogReporter` for application-side event ingestion. Never ship a
|
|
15
|
+
management API key in browser, desktop, or mobile code.
|
|
16
|
+
|
|
17
|
+
## Managed private Registry
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
client.managed_registry.set_namespace("alice-space") # Globally unique; existing images and references are migrated.
|
|
21
|
+
repositories = client.managed_registry.repositories()
|
|
22
|
+
references = client.managed_registry.references("alice-space/team/api")
|
|
23
|
+
subscriptions = client.managed_registry.image_auto_updates()
|
|
24
|
+
client.managed_registry.delete_repository("alice-space/team/obsolete") # Deletes every tag and manifest when unreferenced.
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
托管 Registry 支持项目镜像自动更新订阅。
|
|
29
|
+
|
|
30
|
+
镜像部署前可调用 `client.managed_registry.connect_image_registry()` 建立 pull-only 镜像连接。
|
|
31
|
+
|
|
32
|
+
```python
|
|
33
|
+
connection = client.managed_registry.connect_image_registry()
|
|
34
|
+
client.projects.save_image_auto_update(42, connection["id"], "alice-space/team/api", tag="latest")
|
|
35
|
+
# Pause/resume without losing the saved tag or update policy.
|
|
36
|
+
saved = client.projects.image_auto_update(42)
|
|
37
|
+
client.projects.save_image_auto_update(
|
|
38
|
+
42, saved["registry_id"], saved["repository"], tag=saved["tag"],
|
|
39
|
+
enabled=False, update_mode=saved["update_mode"],
|
|
40
|
+
ignore_platform_builds=saved["ignore_platform_builds"],
|
|
41
|
+
) # Use enabled=True with the same saved fields to resume.
|
|
42
|
+
# Permanently remove the subscription configuration.
|
|
43
|
+
client.projects.delete_image_auto_update(42)
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Docker login accepts either the DeployEngine account username/password or a separate Registry credential. Create, list, rotate, and revoke separate credentials with `client.managed_registry`; the secret is returned only on creation or rotation, never expires automatically, and remains valid until revoked or rotated. Both user credential types are restricted to the caller's namespace. The SDK returns the one-time secret to the caller and does not store it. The platform generates separate short-lived internal credentials for unattended builds and deployments. Portal JWTs and management API keys are not Docker credentials.
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
import os
|
|
51
|
+
from creat01deployengine import DeployEngine
|
|
52
|
+
from creat01deployengine.errors import PermissionDeniedError
|
|
53
|
+
|
|
54
|
+
try:
|
|
55
|
+
with DeployEngine(
|
|
56
|
+
api_key=os.environ["DEPLOYENGINE_API_KEY"],
|
|
57
|
+
base_url="https://deployengine.creat01.com",
|
|
58
|
+
) as client:
|
|
59
|
+
projects = client.projects.list(page=1, pageSize=20)
|
|
60
|
+
machine = client.machines.get(12)
|
|
61
|
+
except PermissionDeniedError as exc:
|
|
62
|
+
print(f"missing API scope; request={exc.request_id}")
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from creat01deployengine import AsyncDeployEngine
|
|
67
|
+
|
|
68
|
+
async with AsyncDeployEngine(api_key=key) as client:
|
|
69
|
+
projects = await client.projects.list()
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Resource map
|
|
73
|
+
|
|
74
|
+
| Attribute | Purpose | Typical scope |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| `projects` | CRUD, precheck, deployments, releases, deploy/restart streams | `read`, `deploy` |
|
|
77
|
+
| `machines` | CRUD, recommendations, Agent state, port checks | `machines` |
|
|
78
|
+
| `workflows` | Task progress, detail, termination | `read`, `deploy` |
|
|
79
|
+
| `certificates` | CRUD, upload, manual/automatic Let's Encrypt renewal, deployment | `certificates` |
|
|
80
|
+
| `domains` | Domain CRUD and DNS records | `read` |
|
|
81
|
+
| `load_balancers` | Gateway config, sync, bindings, listeners | `infrastructure` |
|
|
82
|
+
| `alerts` | Alert contacts and notification sending | `monitoring` |
|
|
83
|
+
| `payments` | Payment orders and refunds | `business` |
|
|
84
|
+
| `authentication` | Project account/password registration, login, recovery and sessions; SMS/email code requests take an owner-scoped `credential_id` per call | public `projectId` / end-user bearer token |
|
|
85
|
+
| `feedback` | Customer feedback ticket links | `business` |
|
|
86
|
+
| `tracking` | Project event ingestion | `business` API Key scope |
|
|
87
|
+
| `users` | Admin-only user list/create/role/deletion | administrator role; JWT for writes |
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
with DeployEngine(access_token=admin_jwt) as admin:
|
|
91
|
+
page = admin.users.list(page=1, page_size=20, role="user", keyword="ops")
|
|
92
|
+
created = admin.users.create({"username": "operator", "password": "secret123"})
|
|
93
|
+
admin.users.change_role(created["id"], "admin")
|
|
94
|
+
admin.users.delete(created["id"])
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
User-management writes require an administrator Bearer JWT; the list also
|
|
98
|
+
accepts an administrator API key. Authenticated non-admin users receive
|
|
99
|
+
`PermissionDeniedError`. Business-capability management is likewise admin-only,
|
|
100
|
+
while login, callback, and one-time feedback endpoints keep
|
|
101
|
+
their project credential, signature, or token authentication. Project tracking
|
|
102
|
+
uses the API Key and project name supplied to the tracking resource.
|
|
103
|
+
|
|
104
|
+
```python
|
|
105
|
+
with DeployEngine(api_key=key) as client:
|
|
106
|
+
for event in client.projects.deploy_stream(7, {"branch": "main"}):
|
|
107
|
+
print(event)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Resources return the unwrapped `data` field. Writes are not retried unless an
|
|
111
|
+
idempotency key is present. `DeployEngineError` exposes `status_code`, `code`,
|
|
112
|
+
`request_id`, `details`, and `retryable`. See `AI_USAGE.md` for task recipes.
|
|
113
|
+
|
|
114
|
+
Machine metrics start automatically after machine creation and Agent
|
|
115
|
+
connection, at a system-owned one-minute interval. This SDK does not currently
|
|
116
|
+
expose the `/api/monitor/machines` HTTP resource; `alerts` manages alert
|
|
117
|
+
contacts only. Existing direct HTTP integrations should move threshold/contact
|
|
118
|
+
updates to `PUT /api/monitor/machines/{machine_id}/alert-config`; legacy monitor
|
|
119
|
+
add, remove, and interval endpoints remain compatibility-only.
|
|
120
|
+
|
|
121
|
+
Maintainers can run the opt-in live smoke test with
|
|
122
|
+
`DEPLOYENGINE_E2E_API_KEY=... pytest tests/test_live_api.py`. It performs only
|
|
123
|
+
authenticated list operations and does not deploy or mutate resources.
|
|
124
|
+
|
|
125
|
+
证书续期:`client.certificates.renew(cert_id)` 会触发已有部署机器的证书更新及 Nginx 重载;任一机器失败时返回错误,需检查对应部署记录。
|
|
126
|
+
|
|
127
|
+
## Load balancer sync
|
|
128
|
+
|
|
129
|
+
`client.load_balancers.sync(id)` synchronizes bound project gateway configuration. HTTP 200 is not proof of application: check `sync_status`, `last_sync_error`, `config_revision`, and `applied_revision` in the returned data. Independent listener records (even disabled ones) are metadata only and make sync fail before remote operations. Configure domains and certificates on the project instead; remove independent listener metadata before retrying. Removing metadata does not remove project sites. New or changed configurations remain `pending` until sync succeeds for the current revision; old `ready` records should be resynced. Methods, paths and response envelopes remain compatible; this corrects false success reporting.
|
|
130
|
+
|
|
131
|
+
机器证书部署查询:Python `client.certificates.machine_deployments(machine_id)`,TypeScript `client.api.certificates.machineDeployments(machineId)` 调用 `GET /api/certificates/machines/{machine_id}/deployments`,返回 `{ list: [...] }`。仅返回当前用户所拥有机器的部署元数据与证书名称/域名,不包含 PEM 或私钥内容;不可见或不存在的机器返回 HTTP 404。该能力为兼容性新增。
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
### 项目 SSL 证书
|
|
135
|
+
|
|
136
|
+
项目域名发布默认要求 HTTPS,必须先确认每个域名的证书绑定并部署到入口机器;无证书时不会静默降级。需要 HTTP 时显式保存 `mode: "http"`。旧客户端请求字段保持兼容,但未准备证书的域名发布现在返回就绪错误;运行中的服务不会因升级自动改配置。证书申请继续使用独立证书工作流。
|
|
137
|
+
|
|
138
|
+
Python:`client.api.projects.ssl(id, check_remote=True)`、`save_ssl(id, {"mode": "https", "bindings": {"app.example.com": certificate_id}})`、`deploy_ssl(id, "app.example.com")`、`preview_ssl(id)`、`apply_ssl(id, preview["revision"])`。TypeScript 对应 `ssl(id, true)`、`saveSsl`、`deploySsl`、`previewSsl`、`applySsl`。查询可传 `host` 准备待新增域名。类型为 `ProjectSslPolicy`、`ProjectSslStatus`、`ProjectSslPreview`。保存绑定只修改期望配置,应用前必须审阅预览的站点替换内容;409 表示未就绪、操作冲突或需要重新预览。返回元数据不含证书/私钥正文。应用只核对入口本机 TLS;公网 DNS、CDN、防火墙需单独验证。
|
|
139
|
+
|
|
140
|
+
工作流 `GET /api/workflow-tasks/{task_id}/progress` 的 `logPreview` 为最多 12,000 字符的日志尾部;完整保留日志使用 `/detail` 的 `logContent`。接口路径、字段与认证保持兼容。 零停机清理恢复及按次诊断语义见 [SDK 说明](../../docs/sdk.md)。
|
|
141
|
+
|
|
142
|
+
### 系统自动识别与容器盘点
|
|
143
|
+
|
|
144
|
+
机器创建/修改连接信息自动保存系统版本和架构;读取 `platform` 与 `platformProbeAt`,无需手动填写系统。Python 使用 `client.machines.container_inventory(machine_id=7)`,TypeScript 使用 `client.api.machines.containerInventory(7)`;省略机器 ID 查询本人全部机器。`machines[]` 包含采集时间、ready/unavailable、errorCode 与容器列表,局部失败必须单独处理。容器的 `readOnly` 与 `projectBindings` 指示项目生命周期归属;项目容器只读,通用写操作(包括强制删除)返回 409,须通过项目流程管理。大规模盘点最长 90 秒,请将客户端 timeout 配置为 120 秒。容器操作使用机器 ID 与完整容器 ID;409 表示操作未完成,先刷新确认再重试。详见[SDK 说明](../../docs/sdk.md)。
|
|
145
|
+
|
|
146
|
+
### 部署失败诊断与日志兼容性
|
|
147
|
+
|
|
148
|
+
部署失败事件的 `content` 可包含容器状态与启动日志;失败或清理后可用通用 request 查询原项目日志接口。现有方法、字段和认证保持兼容;详见[SDK 说明](../../docs/sdk.md)。
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Public type models importable from ``creat01deployengine.models``."""
|
|
2
|
+
|
|
3
|
+
from .project_ssl import ProjectSslPolicy, ProjectSslStatus, ProjectSslPreview
|
|
4
|
+
from .common import Page
|
|
5
|
+
from .infrastructure import NginxConfigInfo, NginxConfigContent, NginxProjectBinding, LoadBalancer, MachineCertificateDeployment, ContainerInventory, InventoryContainer, InventoryMachine, ProjectContainerBinding
|
|
6
|
+
from .projects import CreateProjectRequest, Project
|
|
7
|
+
from .users import CreateUserRequest, ManagedUser, UserPage, UserRole
|
|
8
|
+
|
|
9
|
+
__all__ = [
|
|
10
|
+
"NginxConfigInfo", "NginxConfigContent", "NginxProjectBinding",
|
|
11
|
+
"CreateProjectRequest",
|
|
12
|
+
"LoadBalancer",
|
|
13
|
+
"ContainerInventory",
|
|
14
|
+
"ProjectContainerBinding",
|
|
15
|
+
"InventoryContainer",
|
|
16
|
+
"InventoryMachine",
|
|
17
|
+
"MachineCertificateDeployment",
|
|
18
|
+
"Page",
|
|
19
|
+
"Project",
|
|
20
|
+
"ProjectSslPolicy",
|
|
21
|
+
"ProjectSslStatus",
|
|
22
|
+
"ProjectSslPreview",
|
|
23
|
+
"CreateUserRequest",
|
|
24
|
+
"ManagedUser",
|
|
25
|
+
"UserPage",
|
|
26
|
+
"UserRole",
|
|
27
|
+
]
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
"""Typed mappings for infrastructure resources."""
|
|
2
|
+
|
|
3
|
+
from typing import Optional, TypedDict
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class LoadBalancer(TypedDict, total=False):
|
|
7
|
+
"""DeployEngine-managed load balancer summary."""
|
|
8
|
+
id: int
|
|
9
|
+
name: str
|
|
10
|
+
enabled: bool
|
|
11
|
+
gatewayMachineId: int
|
|
12
|
+
sync_status: str
|
|
13
|
+
config_revision: int
|
|
14
|
+
applied_revision: int
|
|
15
|
+
last_sync_error: Optional[str]
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class MachineCertificateDeployment(TypedDict, total=False):
|
|
19
|
+
"""Public certificate deployment metadata; excludes certificate and key contents."""
|
|
20
|
+
id: int
|
|
21
|
+
certificate_id: int
|
|
22
|
+
machine_id: int
|
|
23
|
+
cert_path: str
|
|
24
|
+
key_path: Optional[str]
|
|
25
|
+
deployed: int
|
|
26
|
+
certificate_name: Optional[str]
|
|
27
|
+
certificate_domain_name: Optional[str]
|
|
28
|
+
created_at: Optional[str]
|
|
29
|
+
updated_at: Optional[str]
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class ProjectContainerBinding(TypedDict):
|
|
33
|
+
"""Project that owns the lifecycle of a container on this machine."""
|
|
34
|
+
projectId: int
|
|
35
|
+
projectName: str
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class InventoryContainer(TypedDict):
|
|
39
|
+
"""A current Docker container, identified by full ID within its machine."""
|
|
40
|
+
readOnly: bool
|
|
41
|
+
projectBindings: list[ProjectContainerBinding]
|
|
42
|
+
id: str
|
|
43
|
+
name: str
|
|
44
|
+
image: str
|
|
45
|
+
state: str
|
|
46
|
+
status: str
|
|
47
|
+
ports: str
|
|
48
|
+
createdAt: str
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class InventoryMachine(TypedDict):
|
|
52
|
+
"""Collection status; unavailable is never an empty successful inventory."""
|
|
53
|
+
machineId: int
|
|
54
|
+
machineName: str
|
|
55
|
+
status: str
|
|
56
|
+
errorCode: Optional[str]
|
|
57
|
+
checkedAt: str
|
|
58
|
+
containers: list[InventoryContainer]
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
class ContainerInventory(TypedDict):
|
|
62
|
+
"""Per-machine results of a live collection across owned machines."""
|
|
63
|
+
machines: list[InventoryMachine]
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
class NginxProjectBinding(TypedDict):
|
|
67
|
+
"""Owner of a project configuration on this machine."""
|
|
68
|
+
projectId: int
|
|
69
|
+
projectName: str
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class NginxConfigInfo(TypedDict):
|
|
73
|
+
"""Machine Nginx site metadata; only readOnly=False permits mutations."""
|
|
74
|
+
filePath: str
|
|
75
|
+
name: str
|
|
76
|
+
enabled: int
|
|
77
|
+
readOnly: bool
|
|
78
|
+
projectBindings: list[NginxProjectBinding]
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class NginxConfigContent(TypedDict):
|
|
82
|
+
"""Configuration content and its current server-side ownership policy."""
|
|
83
|
+
filePath: str
|
|
84
|
+
content: str
|
|
85
|
+
readOnly: bool
|
|
86
|
+
projectBindings: list[NginxProjectBinding]
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
"""Project certificate contracts; certificate and private-key PEM never appear here."""
|
|
2
|
+
from typing import Literal, Optional, TypedDict
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
class ProjectSslPolicy(TypedDict):
|
|
6
|
+
"""Explicit access protocol and confirmed per-host certificate IDs."""
|
|
7
|
+
mode: Literal['https', 'http']
|
|
8
|
+
bindings: dict[str, int]
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class ProjectSslCandidate(TypedDict):
|
|
12
|
+
"""Public certificate metadata and actual PEM usability."""
|
|
13
|
+
id: int
|
|
14
|
+
name: str
|
|
15
|
+
usable: bool
|
|
16
|
+
reason: Optional[str]
|
|
17
|
+
expireAt: Optional[str]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class ProjectSslDeployment(TypedDict):
|
|
21
|
+
"""Ingress file paths and recorded deployment state."""
|
|
22
|
+
id: int
|
|
23
|
+
cert_path: str
|
|
24
|
+
key_path: Optional[str]
|
|
25
|
+
deployed: int
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class ProjectSslDomain(TypedDict):
|
|
29
|
+
"""Separate certificate-library, machine and site facts for a host."""
|
|
30
|
+
host: str
|
|
31
|
+
certificateId: Optional[int]
|
|
32
|
+
recommendedId: Optional[int]
|
|
33
|
+
candidates: list[ProjectSslCandidate]
|
|
34
|
+
deployment: Optional[ProjectSslDeployment]
|
|
35
|
+
ready: bool
|
|
36
|
+
error: Optional[str]
|
|
37
|
+
siteUsesCertificate: Optional[bool]
|
|
38
|
+
siteError: Optional[str]
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class ProjectSslStatus(ProjectSslPolicy):
|
|
42
|
+
"""Owned project TLS readiness without certificate or key contents."""
|
|
43
|
+
machineId: Optional[int]
|
|
44
|
+
running: bool
|
|
45
|
+
domains: list[ProjectSslDomain]
|
|
46
|
+
checkedAt: Optional[str]
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class ProjectSslSiteChange(TypedDict):
|
|
50
|
+
"""Current and generated site text requiring explicit review."""
|
|
51
|
+
host: str
|
|
52
|
+
name: str
|
|
53
|
+
before: str
|
|
54
|
+
after: str
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class ProjectSslPreview(TypedDict):
|
|
58
|
+
"""Reviewed site changes and their optimistic concurrency revision."""
|
|
59
|
+
revision: str
|
|
60
|
+
machineId: int
|
|
61
|
+
changes: list[ProjectSslSiteChange]
|
{creat01deployengine-1.0.0 → creat01deployengine-1.0.1}/src/creat01deployengine/models/projects.py
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"""Typed mappings for common project responses and create requests."""
|
|
2
2
|
|
|
3
|
-
from typing import
|
|
3
|
+
from typing import TypedDict
|
|
4
4
|
|
|
5
5
|
|
|
6
6
|
class Project(TypedDict, total=False):
|
|
@@ -11,7 +11,10 @@ class Project(TypedDict, total=False):
|
|
|
11
11
|
createdAt: str
|
|
12
12
|
|
|
13
13
|
|
|
14
|
-
class
|
|
15
|
-
"""Minimum supported request for creating a project."""
|
|
14
|
+
class _CreateProjectRequired(TypedDict):
|
|
16
15
|
name: str
|
|
17
|
-
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class CreateProjectRequest(_CreateProjectRequired, total=False):
|
|
19
|
+
"""Minimum supported request for creating a project."""
|
|
20
|
+
machineId: int
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Typed request and response mappings for administrator user management."""
|
|
2
|
+
|
|
3
|
+
from typing import Literal, Optional, TypedDict
|
|
4
|
+
|
|
5
|
+
UserRole = Literal["admin", "user"]
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class ManagedUser(TypedDict, total=False):
|
|
9
|
+
"""Non-sensitive user fields returned by administrator APIs."""
|
|
10
|
+
|
|
11
|
+
id: int
|
|
12
|
+
username: str
|
|
13
|
+
email: Optional[str]
|
|
14
|
+
role: UserRole
|
|
15
|
+
created_at: Optional[str]
|
|
16
|
+
updated_at: Optional[str]
|
|
17
|
+
last_login_at: Optional[str]
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class _CreateUserRequired(TypedDict):
|
|
21
|
+
username: str
|
|
22
|
+
password: str
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
class CreateUserRequest(_CreateUserRequired, total=False):
|
|
26
|
+
"""Body accepted when an administrator creates a platform user."""
|
|
27
|
+
|
|
28
|
+
email: Optional[str]
|
|
29
|
+
role: UserRole
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class UserPage(TypedDict):
|
|
33
|
+
"""Paginated administrator user-list response."""
|
|
34
|
+
|
|
35
|
+
items: list[ManagedUser]
|
|
36
|
+
total: int
|
|
37
|
+
page: int
|
|
38
|
+
pageSize: int
|