lazycat-advanced-routing

LazyCat Microservices Advanced Routing

Work in the following order; do not directly apply the old version checklist or old image examples.

1. First calibrate against the official specification

For any packaging, build, or routing configuration task, first read references/spec-sync.md, verify the current official source text according to the process in it, and confirm the target lzcos and lzc-cli versions. The repository reference documentation is a snapshot; if it conflicts with the current official documentation, the official documentation prevails.

LPK V2 must split configuration:

• package.yml：package、version、name、description, permissions, and other static package information.
• lzc-manifest.yml：application、services and other runtime structures.
• Do not continue writing old metadata at the top level of the V2 manifest, and do not add nonexistent application.secondary_domains。

2. Choose the correct traffic mechanism

Requirement	Use	Key rules
Simple HTTP/HTTPS, static files, or starting a local program	application.routes	URL_PATH=UPSTREAM; the matched path prefix is removed by default
Preserve paths, route by domain prefix, control Host/Header/TLS verification	application.upstreams	backend only supports http、https、file
TCP/UDP, databases, or other non-HTTP protocols	application.ingress	L4 passthrough, does not go through platform HTTP authentication
Complex rewrites that built-in capabilities cannot express	In-application reverse proxy	Prefer the verified current image; do not copy outdated app-proxy labels

Protocol boundaries must be clear:

• routes supports http(s)://、file:///、exec://端口,程序路径。
• upstreams[].backend supports http、https、file, does not support exec://; when a program needs to be started, use backend_launch_command。
• ingress only declares tcp or udp; do not use it in place of ordinary HTTP routing.

3. Hard rules for domains and service discovery

• Every application automatically has <prefix>-<实际子域名>.<微服根域> prefix domains in the form; use for routing by domain upstreams[].domain_prefix。
• The actual assigned domain may change due to conflicts or multiple instances; it can only be obtained from LAZYCAT_APP_DOMAIN ; do not construct the final domain by hardcoding according to application.subdomain .
• Within the same application, usually use http://<service>:<port>. When an in-application proxy needs to receive the full ingress Host, use the official multi-domain approach <service>.<package-id>.lzcapp。
• .lzcapp Service DNS is not a cross-application invocation mechanism. To access another application's HTTP endpoint on behalf of a user, use app.<target-package-id>.lzcx, and handle delegated permissions and user tickets according to the official inter-application access documentation.
• Prefix domain traffic ignores application.ingress; L4 only uses the ingress corresponding to the application's default domain.

4. Risk boundaries

• use_backend_host controls HTTP Host, not an officially declared TLS SNI switch; the HTTPS backend should specify a hostname matching the certificate.
• disable_backend_ssl_verify disables backend certificate verification and can only be used after the risk is clearly understood.
• L4 forwarding has no platform account authentication; the application must implement protocol authentication itself.
• Taking over 80/443 bypasses authentication, automatic wake-up, platform certificates, and routes/upstreams, and yes_i_want_80_443: truemust be explicitly set. The vast majority of applications should not do this.

5. Read progressively as needed

Only load the documentation needed for the current problem:

• Simple routing, protocols, and service DNS:references/route.md
• upstreams, Host/TLS, complex proxies:references/advanced-routes.md
• Domain prefixes, multi-domain routing:references/secondary-domains.md
• TCP/UDP and 80/443 risks:references/l4forward.md

Before outputting the configuration, check at least: whether the file is split according to V2, whether fields belong to the correct level, whether protocols match, whether cross-application DNS is misused, whether unauthenticated entry points are expanded, and whether the fields used satisfy the target system version.