Add self-contained relay deployment project and operational guidance

This commit is contained in:
ex_tianzy
2026-10-27 17:51:43 +08:00
parent 011a7797ee
commit b774941890
49 changed files with 4454 additions and 0 deletions
+140
View File
@@ -0,0 +1,140 @@
"""Initialize a NEW deployment only. Run as root inside the application image."""
import argparse
import ipaddress
import os
import re
import secrets
import ssl
from datetime import datetime, timedelta, timezone
from pathlib import Path
from urllib.parse import urlsplit
from cryptography import x509
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ed25519
from cryptography.x509.oid import NameOID
from dotenv import dotenv_values, set_key
from relay.crypto import issue_ca, pem_private
def initialize(root, test_cert=False):
root = Path(root)
if os.name != 'nt' and os.geteuid() != 0:
raise ValueError('Run initialization as root for container UID 10001 ownership')
if (root / '.env').exists() or (root / 'runtime/connector/connector.key').exists():
raise ValueError('Existing deployment detected; initialization will not overwrite it')
settings = {k: v for k, v in dotenv_values(root / 'settings.env').items() if v is not None}
required = ['HN_PUBLIC_URL', 'HN_FEISHU_API_BASE', 'HN_FEISHU_AUTHORIZE_URL']
for field in required:
value = settings.get(field, '')
parsed = urlsplit(value)
if parsed.scheme != 'https' or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
raise ValueError(f'{field} must be a valid HTTPS URL')
if parsed.hostname.endswith('.invalid'):
raise ValueError(f'Configure {field} before initializing')
public = urlsplit(settings['HN_PUBLIC_URL'])
if public.path not in ('', '/'):
raise ValueError('HN_PUBLIC_URL must have no path prefix')
if (public.port or 443) != int(settings.get('HN_HTTPS_PORT', '443')):
raise ValueError('Public URL port must match HN_HTTPS_PORT')
if settings.get('HN_FEISHU_ENABLED', 'true').lower() == 'true':
if not all(settings.get(k) for k in ['HN_FEISHU_APP_ID', 'HN_FEISHU_APP_SECRET']):
raise ValueError('Configure platform app ID and secret')
if not re.fullmatch(r'[a-z0-9][a-z0-9_-]*', settings.get('COMPOSE_PROJECT_NAME', 'hainuo-relay')):
raise ValueError('Invalid Compose project name')
tls = root / 'runtime/tls'
tls.mkdir(parents=True, exist_ok=True)
cert_path, key_path = tls / 'server.pem', tls / 'server.key'
if test_cert:
if cert_path.exists() or key_path.exists():
raise ValueError('Refusing to replace an existing TLS certificate')
key = ed25519.Ed25519PrivateKey.generate()
name = x509.Name([x509.NameAttribute(NameOID.COMMON_NAME, public.hostname)])
try:
san = x509.IPAddress(ipaddress.ip_address(public.hostname))
except ValueError:
san = x509.DNSName(public.hostname)
now = datetime.now(timezone.utc)
cert = (x509.CertificateBuilder().subject_name(name).issuer_name(name).public_key(key.public_key())
.serial_number(x509.random_serial_number()).not_valid_before(now-timedelta(minutes=5))
.not_valid_after(now+timedelta(days=30))
.add_extension(x509.SubjectAlternativeName([san]), critical=False).sign(key, None))
key_path.write_bytes(pem_private(key))
cert_path.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
validate_tls(cert_path, key_path, public.hostname)
ca_key, ca = issue_ca()
signer = ed25519.Ed25519PrivateKey.generate()
for folder in ['runtime/trust', 'runtime/connector', 'runtime/issuer']:
(root / folder).mkdir(parents=True, exist_ok=False)
(root / 'runtime/trust/ca.pem').write_bytes(ca.public_bytes(serialization.Encoding.PEM))
(root / 'runtime/trust/connector.pub').write_bytes(signer.public_key().public_bytes(
serialization.Encoding.PEM, serialization.PublicFormat.SubjectPublicKeyInfo))
(root / 'runtime/connector/connector.key').write_bytes(pem_private(signer))
(root / 'runtime/issuer/ca.key').write_bytes(pem_private(ca_key))
redis_pass, db_pass = secrets.token_hex(32), secrets.token_hex(32)
url = settings['HN_PUBLIC_URL'].rstrip('/')
settings.update(HN_ENVIRONMENT='production', HN_PUBLIC_URL=url,
HN_ROUTER_URL='wss://' + urlsplit(url).netloc + '/device/ws',
HN_ADMIN_SECRET=secrets.token_hex(32), HN_INTERNAL_SECRET=secrets.token_hex(32),
HN_REDIS_PASSWORD=redis_pass, HN_POSTGRES_PASSWORD=db_pass,
HN_REDIS_URL=f'redis://:{redis_pass}@redis:6379/0',
HN_DATABASE_URL=f'postgresql://hainuo:{db_pass}@postgres:5432/hainuo',
HN_FEISHU_ENCRYPT_KEY='', HN_FEISHU_VERIFICATION_TOKEN='',
HN_PROXY_ENABLED='false', HN_DEVICE_DOMAIN='')
tmp = root / '.env.initializing'
tmp.touch(mode=0o600, exist_ok=False)
for key, value in settings.items():
if '\n' in value or '\r' in value:
raise ValueError('Multiline settings are unsupported')
set_key(tmp, key, value, quote_mode='always')
tmp.replace(root / '.env')
for folder in ['runtime/connector', 'runtime/issuer']:
path = root / folder
path.chmod(0o700)
if os.name != 'nt':
os.chown(path, 10001, 10001)
for file in path.iterdir():
file.chmod(0o600)
if os.name != 'nt':
os.chown(file, 10001, 10001)
(root / '.env').chmod(0o600)
(root / 'settings.env').chmod(0o600)
tls.chmod(0o700)
key_path.chmod(0o600)
cert_path.chmod(0o644)
(root / 'runtime/trust').chmod(0o755)
for path in (root / 'runtime/trust').iterdir():
path.chmod(0o644)
print('Initialized new deployment. No credentials printed. Preserve runtime/issuer/ca.key securely.')
def validate_tls(cert_path, key_path, hostname):
context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
context.load_cert_chain(str(cert_path), str(key_path))
cert = x509.load_pem_x509_certificate(cert_path.read_bytes())
now = datetime.now(timezone.utc)
if not cert.not_valid_before_utc <= now <= cert.not_valid_after_utc:
raise ValueError('Gateway TLS certificate is not currently valid')
san = cert.extensions.get_extension_for_class(x509.SubjectAlternativeName).value
try:
address = ipaddress.ip_address(hostname)
except ValueError:
host = hostname.encode('idna').decode().lower()
def matches(name):
name = name.lower()
return name == host or (name.startswith('*.') and name.count('*') == 1
and len(host.split('.')) == len(name.split('.'))
and host.split('.', 1)[1] == name[2:])
valid = any(matches(x) for x in san.get_values_for_type(x509.DNSName))
else:
valid = address in san.get_values_for_type(x509.IPAddress)
if not valid:
raise ValueError('Gateway TLS certificate hostname mismatch')
if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('--root', default='/work')
parser.add_argument('--test-cert', action='store_true')
args = parser.parse_args()
initialize(args.root, args.test_cert)