For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /operations/cli-and-config.md.
  • 简体中文
  • CLI 命令、管理员密码重置与环境变量参考

    Yearning v4 编译为单二进制文件 yearning,配置优先级严格固定为:

    内置默认值 < YAML 配置文件 (--config) < YEARNING_* 环境变量

    1. 高频运维操作:内置 admin 被锁后重置密码

    内置超级管理员 admin 连续输错 5 次密码后会被锁定(登录返回 1102 ADMIN_PASSWORD_LOCKED),无法在网页端解锁,必须由运维人员在部署服务器通过交互式终端重置(支持服务运行中在线执行,无需停机):

    二进制部署环境

    # 支持子命令或兼容旧版 --reset-admin-password 参数,必须从交互式 TTY 输入(禁止管道传明文)
    ./yearning --reset-admin-password --config /etc/yearning/config.yaml
    # 按提示输入至少 12 位新密码并二次确认(屏幕不回显)
    # 成功后输出:admin password reset: ok (sessions revoked, lockout cleared, audit written)

    Docker Compose 环境

    # 使用 -it 分配交互式伪终端执行
    docker compose exec -it yearning /yearning --reset-admin-password

    Kubernetes 环境

    kubectl exec -it deploy/yearning-control-plane -n yearning -- /yearning --reset-admin-password

    重置完成后:原 admin 全部活跃会话立刻失效、失败锁定计数清零,同时写入 admin.password_reset_cli 审计日志。


    2. 全部 CLI 子命令速查

    命令用途常用参数
    yearning serve启动控制面、调度器、SSE 总线与 Web UI--config <yaml>、--listen <addr>、--bootstrap-admin-password-file <file>、--migration-mode
    yearning migrateSchema 迁移与 v3 -> v4 停机迁移preflight / dry-run / apply / verify、--config、--run-id、--migrations-dir、--catalog、--report-dir
    yearning reset-admin-password交互式重置内置 admin 密码(等价 --reset-admin-password)--config <yaml>
    yearning mock启动无外部依赖的契约 Mock Server(前端联调用)基于 api/openapi/yearning-v4.yaml
    yearning version输出版本号、Commit、架构与 Go 版本无

    3. 完整 YEARNING_* 环境变量与 config.yaml 映射

    环境变量对应 config.yaml 路径默认值说明
    YEARNING_ENVIRONMENTenvironment空(环回开发)development 或 production;非环回监听(如 0.0.0.0:8080)时必填
    YEARNING_SERVER_LISTEN_ADDRESSserver.listen_address0.0.0.0:8080HTTP 监听地址
    YEARNING_SERVER_SHUTDOWN_GRACE_SECONDSserver.shutdown_grace_seconds20优雅退出等待秒数(1..300)
    YEARNING_SERVER_READ_HEADER_TIMEOUT_SECONDSserver.read_header_timeout_seconds10读请求头超时
    YEARNING_SERVER_READ_TIMEOUT_SECONDSserver.read_timeout_seconds60读请求体超时
    YEARNING_SERVER_WRITE_TIMEOUT_SECONDSserver.write_timeout_seconds120写响应超时
    YEARNING_SERVER_IDLE_TIMEOUT_SECONDSserver.idle_timeout_seconds120Keep-Alive 空闲超时
    YEARNING_TRUSTED_PROXIEStrusted_proxies空逗号分隔的受信任反代 CIDR(如 127.0.0.1/32,10.0.0.0/8)
    YEARNING_DATABASE_HOSTdatabase.host必填PostgreSQL 主机
    YEARNING_DATABASE_PORTdatabase.port必填PostgreSQL 端口(通常 5432)
    YEARNING_DATABASE_USERdatabase.user必填应用角色(生产须为非超级用户 yearning_app)
    YEARNING_DATABASE_PASSWORDdatabase.password必填数据库密码
    YEARNING_DATABASE_DBNAMEdatabase.dbname必填元数据库名
    YEARNING_DATABASE_SSLMODEdatabase.sslmodeprefer生产模式强制仅接受 verify-ca 或 verify-full
    YEARNING_DATABASE_SSLROOTCERTdatabase.sslrootcert空私有 CA 证书路径(缺失时走系统信任库)
    YEARNING_DATABASE_MAX_OPEN_CONNSdatabase.max_open_conns50连接池最大连接数
    YEARNING_DATABASE_MAX_IDLE_CONNSdatabase.max_idle_conns15连接池最大空闲连接
    YEARNING_DATABASE_CONN_MAX_LIFETIME_MINUTESdatabase.conn_max_lifetime_minutes10连接最大存活分钟数
    YEARNING_RETENTION_DATABASE_DSNretention.database_dsn生产必填yearning_retention 独立清理角色 libpq 连接串
    YEARNING_KEY_PROVIDER_KINDkey_provider.kindfile密钥提供者类型
    YEARNING_KEY_PROVIDER_PATHkey_provider.path必填keyring.json 路径(文件权限须 0400 或 0440)
    YEARNING_SESSION_COOKIE_NAMEsession.cookie_nameyearning_session会话 Cookie 名
    YEARNING_SESSION_SECUREsession.securetrue仅在无 HTTPS 的本地开发评测中可改为 false
    YEARNING_LOGGING_LEVELlogging.levelinfodebug / info / warn / error
    YEARNING_LOGGING_FORMATlogging.formatjson固定为结构化 json
    YEARNING_OBSERVABILITY_SERVICE_NAMEobservability.service_nameyearning服务名
    YEARNING_OBSERVABILITY_DEPLOYMENT_IDobservability.deployment_id空部署环境标识
    YEARNING_OBSERVABILITY_INSTANCE_IDobservability.instance_id空Pod / 节点实例标识
    YEARNING_SCHEMA_MIGRATIONS_DIR仅环境变量/usr/share/yearning/db-migrationsReadiness exact_schema_version 校验使用的迁移目录
    YEARNING_RELEASE_FEED_UPSTREAM_URLrelease_feed.upstream_urlGitHub Releases自定义版本检测上游 URL
    YEARNING_ALLOW_LOOPBACK_TARGETS仅环境变量false仅允许在 development 调试本机目标库;production 开启会直接拒绝启动