AppServer启动与依赖装配

本文承接AppServer架构总览，面向已经理解 transport、connection 和 MessageProcessor 的读者。本文回答生产 App Server 启动时依赖按什么顺序创建、哪些错误允许降级、哪些错误会阻断启动，以及 transport 何时开始接收连接；不展开具体 processor 的业务实现。

1. 启动主线

真实入口是 CLI main，它把参数转换为 AppServerRuntimeOptions，再调用 run_main_with_transport_options。后者负责配置预加载、认证、环境、OTel、state DB、transport 和 processor 装配。

2. CLI入口

源码位置：codex-rs/app-server/src/main.rs :: main

let AppServerArgs {
    config_overrides,
    code_mode_host,
    listen,
    session_source,
    auth,
    strict_config,
    ..
} = AppServerArgs::parse();
let auth = auth.try_into_settings()?;
let runtime_options = AppServerRuntimeOptions {
    code_mode_host_transport: code_mode_host.into(),
    ..Default::default()
};
run_main_with_transport_options(
    arg0_paths,
    config_overrides,
    loader_overrides,
    strict_config,
    false,
    listen,
    session_source,
    auth,
    runtime_options,
).await?;

CLI 层只负责参数解析和启动模式选择；真正的 config/auth 依赖在 runtime function 中创建。listen 选择 stdio、Unix socket、WebSocket 或 off。

3. Config预加载

源码位置：codex-rs/app-server/src/lib.rs :: run_main_with_transport_options

let mut config_manager = ConfigManager::new(
    codex_home.to_path_buf(),
    cli_kv_overrides,
    loader_overrides,
    strict_config,
    Default::default(),
    arg0_paths.clone(),
    Arc::new(NoopThreadConfigLoader),
);
match config_manager.load_latest_config(None).await {
    Ok(config) => {
        let loader = configured_thread_config_loader(&config);
        config_manager.replace_thread_config_loader(loader);
        let auth_manager = AuthManager::shared_from_config(&config, false).await;
        config_manager.replace_cloud_config_bundle_loader(auth_manager, config.chatgpt_base_url.clone(), config.http_client_factory());
    }
    Err(err) => warn!(error = %err, "Failed to preload config for cloud config bundle"),
}

预加载用于安装 thread/cloud config loader。该阶段失败在源码中记录 warning，非 strict 启动可以继续，但 managed cloud config 可能不可用。

4. 最终配置

随后再次读取 config；strict 模式下失败直接返回，非 strict 模式记录 warning 并加载默认配置。之后验证 auth config、创建 code mode provider 和 EnvironmentManager。

5. 运行依赖

源码位置：codex-rs/app-server/src/lib.rs :: run_main_with_transport_options、EnvironmentManager、state runtime 初始化

EnvironmentManager 根据配置和环境路径建立本地/远程执行能力；OTel provider 建立后记录 process start；SQLite state runtime 初始化失败会进入专门错误/备份处理，而不是静默忽略。

6. Transport启动

源码位置：codex-rs/app-server/src/lib.rs :: AppServerTransport 分支

match &transport {
    AppServerTransport::Stdio => {
        start_stdio_connection(transport_event_tx.clone(), &mut handles, client_name_tx).await?;
    }
    AppServerTransport::UnixSocket { socket_path } => {
        handles.push(start_control_socket_acceptor(socket_path.clone(), transport_event_tx.clone(), shutdown_token.clone()).await?);
    }
    AppServerTransport::WebSocket { bind_address } => {
        handles.push(start_websocket_acceptor(*bind_address, transport_event_tx.clone(), shutdown_token.clone(), policy).await?);
    }
    AppServerTransport::Off => {}
}

transport acceptor 启动后，连接事件才会进入 processor loop。Off 允许创建 runtime 但不监听外部连接，适合嵌入或测试模式。

7. Processor装配

源码位置：codex-rs/app-server/src/lib.rs :: MessageProcessor::new

let outgoing_message_sender = Arc::new(OutgoingMessageSender::new(outgoing_tx, analytics_events_client.clone()));
let processor = Arc::new(MessageProcessor::new(MessageProcessorArgs {
    outgoing: outgoing_message_sender,
    analytics_events_client,
    config: Arc::new(config),
    config_manager,
    environment_manager,
    state_db,
    auth_manager,
    session_source,
    remote_control_handle: Some(remote_control_handle.clone()),
    plugin_startup_tasks: runtime_options.plugin_startup_tasks,
}));

processor 装配完成后才会订阅 thread-created 和 running-turn count，并启动连接 map、cleanup tasks 与 remote-control status watcher。依赖共享 owner 由 Arc 传入，生命周期由 processor runtime 管理。

8. 失败与关闭

CLI 解析、auth settings、strict config、auth validation、EnvironmentManager、OTel 和 state DB 属于启动失败边界；preload config warning 和非 strict config error 可以降级。收到 shutdown signal 后，server 会根据 running assistant turn count 进入 drain，等待完成或二次信号强制关闭。

9. 源码验证

main tests 验证 CLI/config override；in-process tests 验证 runtime 依赖装配、initialize handshake 和 shutdown；app-server main tests 验证 strict/non-strict config 与 transport 启动边界。它们证明装配顺序和生命周期，不证明真实外部认证服务或所有 transport 平台行为。

源码位置：

• codex-rs/app-server/src/main_tests.rs :: CLI/runtime
• codex-rs/app-server/src/in_process.rs :: start
• codex-rs/app-server/src/main_tests.rs :: shutdown/config

cd codex-rs
cargo test -p codex-app-server main
cargo test -p codex-app-server in_process
cargo test -p codex-app-server shutdown

10. 启动排查

启动失败时先区分参数解析、配置读取、auth validation、environment/SQLite、transport bind 和 processor 装配；服务已启动但无连接时检查 listen 分支；非 strict 模式行为异常时检查 preload warning 和默认配置 fallback。启动顺序决定后续 processor 能看到哪些依赖。