feat(deploy): 接通 HiFox 待发布自动触发
build / build (push) Successful in 1m27s

将发布人的状态变更与业务验收报告绑定,复用 Gitea 发布及回滚链路。
从部署回执写入运行身份、镜像及主站登录入口,避免重复调度和回写。
This commit is contained in:
姚章浩
2026-11-23 02:57:46 +08:00
parent 91988a0d3b
commit 47428a8b58
5 changed files with 292 additions and 14 deletions
+93
View File
@@ -0,0 +1,93 @@
#!/usr/bin/env python3
"""Submit a HiFox-approved release from the designated CD Agent host."""
import argparse
import base64
import json
import os
from pathlib import Path
import re
import sys
from urllib.error import HTTPError
from urllib.request import ProxyHandler, Request, build_opener
import production_cd as cd
DISPATCH = f'/api/v1/repos/{cd.REPO}/actions/workflows/deploy-production.yml/dispatches?return_run_details=true'
PATH = Path.home() / '.local/state/kg-hifox-release'
RUN_ID = re.compile('[1-9][0-9]{0,14}')
def forge(method, path, payload=None):
request = Request(cd.FORGE + path, method=method,
data=json.dumps(payload).encode() if payload is not None else None)
env = {**os.environ, 'GIT_TERMINAL_PROMPT': '0', 'GIT_ASKPASS': '/bin/false'}
fields = dict(line.split('=', 1) for line in cd.run(
['/usr/bin/git', 'credential', 'fill'], 'read Gitea credential', cwd='/', env=env,
input_data=f'url={cd.FORGE}/{cd.REPO}.git\n\n'.encode()).decode().splitlines() if '=' in line)
cd.require(fields.get('username') and fields.get('password'), 'Gitea credential unavailable')
auth = base64.b64encode(f'{fields["username"]}:{fields["password"]}'.encode()).decode()
request.add_header('Authorization', 'Basic ' + auth)
request.add_header('Content-Type', 'application/json')
with build_opener(ProxyHandler({}), cd.NoRedirect()).open(request, timeout=20) as response:
return json.load(response)
def hifox(cli, *args):
env = {'PATH': '/usr/local/bin:/usr/bin:/bin', 'HOME': str(Path.home()), 'CI': '1'}
raw = cd.run([cli, '--organization-id', cd.ORG, *args, '--output', 'json'], 'read HiFox release record', env=env)
result = json.JSONDecoder().raw_decode(raw.decode().strip())[0]
cd.require(isinstance(result, (dict, list)) and (not isinstance(result, dict)
or (result.get('success') is not False and not result.get('error'))), 'HiFox record unavailable')
return result
def queue(task_id, cli, base=PATH):
cd.require(cd.matches(cd.UUID, task_id), 'use the triggering task UUID')
task = hifox(cli, 'task', 'view', task_id)
if not isinstance(task, dict) or task.get('id') != task_id or task.get('spaceId') != cd.SPACE:
raise cd.CDError('task is outside the release space')
acceptance = cd.metadata(task, 'cd_acceptance') or {}
cd.require(isinstance(acceptance, dict) and cd.matches(cd.SHA, acceptance.get('sha'))
and cd.matches(cd.HASH, acceptance.get('bundle')), 'skip: no registered candidate acceptance')
inputs = dict(action='deploy', confirm='deploy-production', sha=acceptance['sha'], bundle=acceptance['bundle'], task=task_id)
timeline = hifox(cli, 'api', 'get', f'/rest/v1/tasks/{task_id}/timeline')
if not isinstance(timeline, list):
raise cd.CDError('HiFox timeline unavailable')
binding, approved_at = cd.release_approval(task, timeline, inputs)
inputs.update(binding)
since = cd.immutable_file(base / 'active-since').read_text().strip()
cd.require(re.fullmatch(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ', since) and approved_at > since,
'status approval predates activation; enter 待发布 again after acceptance')
claim = base / (binding['approval_event'] + '.json')
with cd.deploy_lock(base / 'dispatch.lock'):
if claim.exists():
result = cd.read_json(cd.immutable_file(claim))
cd.require(result.get('inputs') == inputs, 'HiFox approval already used for a different release')
cd.require(result.get('state') == 'queued', 'dispatch outcome unknown; reconcile Gitea before retry')
return result
result = {'state': 'submitting', 'inputs': inputs, 'started_at': cd.stamp()}
cd.record(claim, result)
response = forge('POST', DISPATCH, {'ref': 'main', 'inputs': inputs})
run_id = str(response.get('workflow_run_id', ''))
cd.require(cd.matches(RUN_ID, run_id), 'dispatch response has no valid run ID; reconcile before retry')
result.update(state='queued', run_id=run_id, run_url=f'{cd.FORGE}/{cd.REPO}/actions/runs/{run_id}')
cd.record(claim, result)
return result
if __name__ == '__main__':
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('task', help='UUID of the task that entered 待发布')
args = parser.parse_args()
executable = Path.home() / '.local/bin/hifox'
try:
print(json.dumps(queue(args.task, str(executable)), ensure_ascii=False))
except HTTPError as exc:
sys.exit(f'CD: Gitea dispatch HTTP {exc.code}; reconcile before retry')
except cd.CDError as exc:
sys.exit(f'CD: {exc}')
except (OSError, KeyError, ValueError, TypeError) as exc:
sys.exit(f'CD: {type(exc).__name__}; inspect the dispatch record')
+114 -9
View File
@@ -29,6 +29,8 @@ ORG = '169e6f7f-e508-4a1f-9a9b-63d240439a3d'
SPACE = '106e05d1-4091-40b9-8c57-f76dc94f7825'
READY = '3e15556f-ca19-417c-8bfd-666634ea5d29'
PUBLISHED = '16185166-b8e9-4761-9926-845a1f41c96d'
RELEASE_OWNER = '39ae59fb-876c-4587-ab5d-a12a841c6c09'
LOGIN_URL = 'http://100.85.111.121:8088/'
ROLES = ('api', 'web', 'worker')
REVISION = 'org.opencontainers.image.revision'
DATA = Path('/opt/knowledge-governance/cd')
@@ -106,11 +108,17 @@ def validate_request(request):
require(matches(SHA, request.get('sha')) and matches(UUID, request.get('task'))
and matches(HASH, request.get('bundle')), 'require full SHA, bundle SHA256 and task UUID')
require(matches(re.compile('[1-9][0-9]{0,14}'), request.get('run_id')), 'invalid Gitea run ID')
event, digest = request.get('approval_event', ''), request.get('acceptance_digest', '')
require((event == '' and digest == '') or
(action == 'deploy' and matches(UUID, event) and matches(HASH, digest)),
'invalid HiFox approval binding')
def guard_proof(request, control_sha):
require(matches(SHA, control_sha), 'invalid workflow source SHA')
binding = {key: request[key] for key in ('run_id', 'action', 'confirm', 'sha', 'bundle', 'task')}
if request.get('approval_event'):
binding.update(approval_event=request['approval_event'], acceptance_digest=request['acceptance_digest'])
binding.update(repository=REPO, target=TARGET, workflow_sha=control_sha)
serialized = json.dumps(binding, sort_keys=True, separators=(',', ':')).encode()
return GUARD_PREFIX + hashlib.sha256(serialized).hexdigest()
@@ -176,11 +184,53 @@ def check_task(task, request, receipt=None):
url = urlsplit(evidence.get('evidence', ''))
require(evidence.get('verdict') == 'passed' and evidence.get('sha') == request['sha']
and evidence.get('bundle') == request['bundle'] and url.scheme == 'https' and url.hostname
and not (url.username or url.password or url.query or url.fragment),
and not (url.username or url.password or url.query)
and (not url.fragment or (url.netloc == 'app.hifox.com' and url.fragment.startswith('comment-')
and matches(UUID, url.fragment.removeprefix('comment-')))),
'missing or changed business acceptance for this commit and bundle')
return evidence
def acceptance_digest(acceptance):
return hashlib.sha256(json.dumps(acceptance, sort_keys=True, separators=(',', ':')).encode()).hexdigest()
def release_approval(task, timeline, request):
evidence = check_task(task, request)
changes = [row for row in timeline if row.get('event') == 'status_changed']
require(bool(changes), 'missing HiFox status history')
approval = changes[-1]
approver = approval.get('actor') or {}
require((approval.get('metadata') or {}).get('to') == '待发布'
and approval.get('createdAt') and approval['createdAt'] == task.get('statusChangedAt')
and approver.get('id') == RELEASE_OWNER and approver.get('type') == 'human'
and matches(UUID, approval.get('id')), 'the latest transition must be an approval by the release owner')
task_url = task.get('url', '')
prefix = task_url + '#comment-'
require(task_url.startswith('https://app.hifox.com/') and evidence['evidence'].startswith(prefix),
'automated release requires the same-task acceptance report')
comment_id = evidence['evidence'].removeprefix(prefix)
require(matches(UUID, comment_id), 'invalid acceptance report ID')
reports = [row for row in timeline if row.get('event') == 'commented' and row.get('id') == comment_id]
require(len(reports) == 1, 'acceptance report missing from task history')
report = reports[0]
body = report.get('content') or ''
require(report.get('createdAt') and (report.get('updatedAt') or report['createdAt']) < approval['createdAt']
and request['sha'] in body and request['bundle'] in body,
'the unchanged report must identify the candidate and predate approval')
binding = {'approval_event': approval['id'], 'acceptance_digest': acceptance_digest(evidence)}
require(all(request.get(key, value) == value for key, value in binding.items()),
'HiFox approval or acceptance changed after dispatch')
return binding, approval['createdAt']
def accepted_task(host, request):
task = host.task(request['task'])
if request.get('approval_event'):
release_approval(task, host.timeline(request['task']), request)
return check_task(task, request)
def release(host, request):
validate_request(request)
path = host.receipt_path
@@ -198,7 +248,7 @@ def release(host, request):
host.approve(request)
manifest = verify_bundle(host.bundle_path(request), request)
host.check_ci(request)
accepted = check_task(host.task(request['task']), request)
accepted = accepted_task(host, request)
before = host.baseline()
host.pre_switch(before, manifest)
receipt = {k: request[k] for k in ('sha', 'task', 'bundle', 'run_id')}
@@ -208,7 +258,7 @@ def release(host, request):
host.load(host.bundle_path(request), manifest)
host.pre_switch(before, manifest)
host.approve(request)
require(check_task(host.task(request['task']), request) == accepted, 'business acceptance changed before switch')
require(accepted_task(host, request) == accepted, 'business acceptance changed before switch')
except (CDError, OSError, ValueError, KeyError) as exc:
receipt.update(state='failed_before_cutover')
record(path, receipt)
@@ -232,6 +282,7 @@ def release(host, request):
receipt.update(state='deployed_hifox_pending', deployed_at=stamp(), evidence=evidence)
receipt['hifox'] = {**evidence, 'target': TARGET, 'bundle': request['bundle'], 'deployed_at': receipt['deployed_at'],
'login_url': LOGIN_URL,
'run_url': f'{FORGE}/{REPO}/actions/runs/{request["run_id"]}'}
record(path, receipt)
return writeback(host, request, receipt)
@@ -423,20 +474,63 @@ class LiveHost:
cli = DATA / 'bin/hifox'
env = {'PATH': '/usr/local/bin:/usr/bin:/bin', 'HOME': str(DATA / 'hifox-home'), 'CI': '1'}
raw = run([str(cli), '--organization-id', ORG, *args, '--output', 'json'], 'HiFox operation', env=env)
result = json.loads(raw)
require(isinstance(result, dict) and result.get('success') is not False and not result.get('error'),
'HiFox did not return a successful object')
result = json.JSONDecoder().raw_decode(raw.decode().strip())[0]
require(isinstance(result, (dict, list)) and (not isinstance(result, dict)
or (result.get('success') is not False and not result.get('error'))),
'HiFox did not return a successful result')
return result
def task(self, task):
return self.hifox('task', 'view', task)
def timeline(self, task):
return self.hifox('api', 'get', f'/rest/v1/tasks/{task}/timeline')
def comment_once(self, task, key, text):
marker = f'KG-CD {key}'
body = f'{text}\n\n`{marker}`'
def present():
return any(row.get('event') == 'commented' and row.get('content') == body
and (row.get('actor') or {}).get('id') == RELEASE_OWNER for row in self.timeline(task))
if not present():
self.hifox('task', 'comment', task, '--body', body)
require(present(), 'HiFox release comment readback mismatch')
def report_failure(self, request):
if not self.receipt_path.exists():
return
receipt = read_json(self.receipt_path)
if any(receipt.get(key) != request[key] for key in ('task', 'sha', 'bundle', 'run_id')):
return
messages = {
'failed_before_cutover': '发布检查失败,未切换主站。',
'rolled_back': '发布核验失败,已恢复原版本并复验。',
'rollback_failed': '发布核验失败,回滚未通过复验,请检查主站。',
'deployed_hifox_pending': '主站已部署并核验,HiFox 回写待完成。请重试回写。',
}
state = receipt['state']
if state in messages:
run_url = f'{FORGE}/{REPO}/actions/runs/{request["run_id"]}'
self.comment_once(request['task'], f'{state} #{request["run_id"]}',
f'{messages[state]}\n\n候选 `{request["sha"]}`\n\n[发布运行]({run_url})')
def callback(self, task_id, task, expected):
if metadata(task, 'cd_release') != expected:
self.hifox('task', 'metadata', 'set', task_id, 'cd_release', json.dumps(json.dumps(expected)))
fresh = self.task(task_id)
check_task(fresh, self.request, {'hifox': expected})
require(metadata(fresh, 'cd_release') == expected, 'HiFox release receipt readback mismatch')
images = '\n'.join(f'- {role} `{expected["images"][role]}`' for role in ROLES)
self.comment_once(task_id, f'published {expected["bundle"]}',
f'云治理主站发布完成,健康检查通过。\n\n'
f'运行版本 `{expected.get("version") or expected["sha"]}`\n\n'
f'提交 `{expected["sha"]}`\n\n{images}\n\n'
f'[登录主站]({LOGIN_URL}) · [发布运行]({expected["run_url"]})')
fresh = self.task(task_id)
check_task(fresh, self.request, {'hifox': expected})
require(metadata(fresh, 'cd_release') == expected, 'HiFox release changed during comment writeback')
if fresh['status']['id'] != PUBLISHED:
self.hifox('task', 'edit', task_id, '--status', PUBLISHED)
final = self.task(task_id)
@@ -554,7 +648,10 @@ class LiveHost:
require(self.runtime() == images, 'running image IDs differ from approved bundle')
require(api_identity(self.containers['api']) == manifest['sha'], 'running API SHA mismatches approval')
assets = self.verify_web_image()
return {'sha': manifest['sha'], 'images': images, 'health': 'ok', 'asset_sha256': assets}
version = image_inspect(images['api'])['Config']['Labels'].get('org.opencontainers.image.version')
if not isinstance(version, str) or not re.fullmatch(r'[0-9A-Za-z.+_-]{1,128}', version):
version = manifest['sha']
return {'sha': manifest['sha'], 'version': version, 'images': images, 'health': 'ok', 'asset_sha256': assets}
return wait_ready(check)
@@ -596,7 +693,8 @@ def event_request(event, env):
require(env.get('GITHUB_EVENT_NAME') == 'workflow_dispatch' and env.get('GITHUB_REF') == 'refs/heads/main'
and env.get('GITHUB_REPOSITORY') == REPO, 'manual dispatch from main required')
inputs = event.get('inputs') or {}
request = {name: inputs.get(name, '') for name in ('action', 'sha', 'task', 'bundle', 'confirm')}
request = {name: inputs.get(name) or '' for name in
('action', 'sha', 'task', 'bundle', 'confirm', 'approval_event', 'acceptance_digest')}
request['run_id'] = env.get('GITHUB_RUN_ID', '')
validate_request(request)
return request
@@ -695,7 +793,14 @@ def cli():
for item in (DATA / 'receipts').glob('*.json'):
if read_json(item)['state'] in ('cutover_started', 'rollback_failed'):
raise CDError('previous deployment outcome requires operator reconciliation')
result = release(host, request)
try:
result = release(host, request)
except (CDError, OSError, ValueError, KeyError):
try:
host.report_failure(request)
except (CDError, OSError, ValueError, KeyError):
print('CD: HiFox failure comment pending', file=sys.stderr)
raise
print(json.dumps({k: result[k] for k in ('state', 'sha', 'task', 'bundle', 'hifox')}, ensure_ascii=False))
+70 -1
View File
@@ -3,9 +3,10 @@ import json
import tempfile
import unittest
from pathlib import Path
from unittest.mock import Mock
from unittest.mock import Mock, patch
import production_cd as cd
import hifox_release_trigger as trigger
SHA = 'a' * 40
@@ -134,6 +135,74 @@ class ProductionCD(unittest.TestCase):
with self.assertRaisesRegex(cd.CDError, 'dispatch proof'):
cd.verify_guard_log(log + log, self.request, trusted)
def hifox_fixture(self):
task = self.host.task.return_value
report = 'ba3ced78-e648-47de-9c17-bccb8f31f36f'
event = 'a3aa1dbe-4082-4972-8e29-ed3e39e26b30'
task.update(url='https://app.hifox.com/example/task/TEST-42', statusChangedAt='2026-11-22T18:00:00Z')
self.acceptance['evidence'] = task['url'] + '#comment-' + report
task['metadata']['cd_acceptance'] = json.dumps(self.acceptance)
timeline = [dict(id=report, event='commented', createdAt='2026-11-22T17:59:00Z',
content=f'验收通过 {SHA} {self.request["bundle"]}'),
dict(id=event, event='status_changed', createdAt=task['statusChangedAt'],
actor={'type': 'human', 'id': cd.RELEASE_OWNER}, metadata={'to': '待发布'})]
return task, timeline
def test_hifox_dispatch_claims_one_transition(self):
task, timeline = self.hifox_fixture()
cd.atomic_write(self.root / 'active-since', b'2026-11-22T17:55:00Z\n')
with patch.object(trigger, 'hifox', side_effect=[task, timeline, task, timeline]), \
patch.object(trigger, 'forge', return_value={'workflow_run_id': 42}) as dispatch:
first = trigger.queue(TASK, 'unused', self.root)
replay = trigger.queue(TASK, 'unused', self.root)
self.assertEqual(first, replay)
self.assertEqual(first['run_id'], '42')
dispatch.assert_called_once_with('POST', trigger.DISPATCH, {'ref': 'main', 'inputs': first['inputs']})
self.assertEqual(first['inputs']['approval_event'], timeline[-1]['id'])
def test_unknown_dispatch_outcome_is_held(self):
task, timeline = self.hifox_fixture()
cd.atomic_write(self.root / 'active-since', b'2026-11-22T17:55:00Z\n')
with patch.object(trigger, 'hifox', side_effect=[task, timeline, task, timeline]), \
patch.object(trigger, 'forge', side_effect=TimeoutError()) as dispatch:
with self.assertRaises(TimeoutError):
trigger.queue(TASK, 'unused', self.root)
with self.assertRaisesRegex(cd.CDError, 'outcome unknown'):
trigger.queue(TASK, 'unused', self.root)
dispatch.assert_called_once()
def test_hifox_gate_requires_owner_and_existing_candidate_report(self):
for failure in ('agent', 'other human', 'mismatched report', 'updated report', 'stale transition', 'no evidence'):
with self.subTest(failure=failure):
task, timeline = self.hifox_fixture()
if failure == 'agent':
timeline[-1]['actor']['type'] = 'agent'
if failure == 'other human':
timeline[-1]['actor']['id'] = TASK
if failure == 'mismatched report':
timeline[0]['content'] = SHA
if failure == 'updated report':
timeline[0]['updatedAt'] = '2026-11-22T19:00:00Z'
if failure == 'stale transition':
task['statusChangedAt'] = '2026-11-22T19:00:00Z'
if failure == 'no evidence':
task['metadata'] = {}
with patch.object(trigger, 'hifox', side_effect=[task, timeline]), patch.object(trigger, 'forge') as forge:
with self.assertRaises(cd.CDError):
trigger.queue(TASK, 'unused', self.root)
forge.assert_not_called()
def test_auto_approval_is_checked_again_before_switch(self):
task, timeline = self.hifox_fixture()
approval, _ = cd.release_approval(task, timeline, self.request)
self.request.update(approval)
self.host.timeline.side_effect = [timeline, timeline[:-1]]
proof = cd.guard_proof(self.request, 'f' * 40)
self.assertNotEqual(proof, cd.guard_proof({**self.request, 'acceptance_digest': 'e' * 64}, 'f' * 40))
with self.assertRaisesRegex(cd.CDError, 'status history'):
self.execute()
self.host.switch.assert_not_called()
def test_target_lock_is_exclusive(self):
path = self.root / 'lock'
with cd.deploy_lock(path):