配置与启动

下载开发包的应用从根目录使用 pnpm dev:all 同时启动前后端，server:go 包装脚本会进入 server/ 并设置私有源环境。.env、日志和存储目录都归应用维护；核心包提供默认配置与平台能力。

环境变量

从同一版本的 server/.env.example 复制到 server/.env 开始，按本机环境修改以下配置：

配置	用途
`APP_NAME`、`APP_ENV`、`APP_DEBUG`	应用名称、环境与调试开关
`APP_HOST`、`APP_PORT`	后端监听地址，模板端口为 `3000`
`APP_KEY`、`JWT_SECRET`	应用加密与 JWT 密钥，由 Artisan 命令生成
`DB_*`	PostgreSQL 连接
`REDIS_*`	Redis 连接与数据库编号
`AGENT_WORKER_ENABLED`	Agent 队列与恢复清扫开关
`WORKFLOW_WORKER_ENABLED`	审批持久任务执行开关
`WORKFLOW_OUTBOX_ENABLED`	审批通知 Outbox 接收开关
`FILES_PRIVATE_ROOT`	私有文件存储根，详见文件中心

独立开发包的 PostgreSQL / Redis 宿主机端口默认为 55432 / 56379；修改端口时同步调整应用 docker-compose.yml 和 server/.env。核心仓库的 Compose 配置用于联合开发，两套配置不要混用。

配置样例中的本地数据库账号仅供开发。真实连接和密钥保存在运行环境中，不写进 Git。

应用装配

入口调用：

bootstrap.Boot(application.Options()).Start()

bootstrap.Options 的 Configure 在核心默认配置之后执行，先于 provider、路由及 worker 的构造。应用需要覆盖默认配置时在这里完成，不在业务请求中反复修改全局配置。

装配会检查迁移签名、路由和扩展声明冲突。错误会阻止服务开放端口，应先修复启动日志中的声明问题。

首次初始化与日常启动

首次安装在应用根目录执行 pnpm app:setup，启动 Compose、生成密钥、迁移并运行种子。日常启动保留已有密钥和数据，执行 pnpm dev:all；需要停止数据库并保留数据时执行 pnpm services:stop。新增表或升级依赖时执行前向迁移。

# 应用根目录；已有应用只执行增量迁移
pnpm server:go run . artisan migrate
pnpm dev:all

0.13.0 开发包已经提供 core:login、core:deps、app:setup、app:upgrade、dev:all、services:stop。首次初始化入口不能用于已有应用升级，已有应用使用 app:upgrade 完成带数据库的升级，具体步骤见升级核心包；旧应用升级核心依赖不会自动获得新版模板命令。

前端开发代理在 web/config/proxy.ts 配置，只作用于开发服务器。构建后的前端由部署环境将 /api 转发到后端。

后台工作

主进程负责平台注册的队列与定时任务。Agent、审批任务及审批 Outbox 有独立开关；关闭 Outbox 不会完成或取消审批任务，关闭 worker 也不等于取消实例。

排查后台工作时分别确认开关、Redis、数据库和日志。modu doctor 的静态检查结果不代表这些运行依赖已经连通。