更新日期：2026-10-31。统一入口为仓库根目录的 ./run.sh，依赖 Bash、Python 3.9+；本地构建另需 Go 1.26.10、Node.js 26 和 npm。平台同时提供 API 与构建后的网页，不需要另起前端开发服务器。
日常命令
| 本地平台 | 用途 |
|---|---|
./run.sh build | 构建当前源码到私有版本目录，不改原 bin/ 或 web/dist |
./run.sh configure | 首次生成 .runtime/launcher/config.json，已有配置不覆盖 |
./run.sh start | 后台启动并等待数据库/API健康检查；已运行时不重复启动 |
./run.sh status | 查看本脚本管理的进程及健康状态 |
./run.sh restart | 优雅停止托管进程，再用当前配置/私有构建启动 |
./run.sh stop | 仅停止本脚本确认身份的进程，保留数据库、密钥和构建 |
./run.sh logs | 显式查看最近100行平台日志 |
本地管理器不接管手动、IDE、systemd或Docker启动的进程。端口占用时拒绝启动，不按端口杀进程，也不自动停止原8090或8108实例。默认监听 127.0.0.1:8090；如被占用，在配置中同时修改 listen 和 origin，例如 127.0.0.1:8110、http://127.0.0.1:8110。
status 的退出码：0=托管进程且健康；3=无可确认的托管进程；4=托管进程存在但健康检查失败。停止超过设定时间时保留记录并提示排查，不强制KILL。健康检查通过仅代表平台与数据库可用，不代表所有业务或外部能力已经验收。
客户首次安装
新客户优先使用 ./run.sh install --email ... --database-url-file /secure/customer-postgres-url，或 ./run.sh docker install --email ... --origin https://实际域名。会生成客户专属平台密钥、公钥和随机初始密码；已有数据不会覆盖。详见客户首次安装与密钥交付。以下保留手动配置/init路径供运维使用。
本地首次准备
- 先准备并启动 PostgreSQL。数据库连接放在权限为0600的私有文件中，内容为一行完整PostgreSQL URL；不要把口令写进命令行参数或公共文档。
- 执行：
./run.sh configure
./run.sh build- 编辑
.runtime/launcher/config.json，将databaseUrlFile设置为私有数据库连接文件的绝对路径。也支持环境变量DATABASE_URL_FILE或DATABASE_URL；若配置了databaseUrlFile，配置文件优先。管理器不会自动读取旧实例的.runtime/database.env。 - 新空数据库需要先准备至少12字节的私有初始密码文件，再初始化：
./run.sh init --email admin@your-company.com --password-file /secure/initial-password
./run.sh start
./run.sh status- 浏览器访问配置中的
origin。init不生成演示账号，不重置已有人员。连接器在企业侧另行登记与运行；本脚本不会默认启用采集、审计投递、真实收款、外部节点或隐私执行后端。
使用已有数据库
本项目如果保留了原 .runtime/platform.key、私有 .runtime/database.env 和 .runtime/releases/v0.5.1/ 配套构建，可直接执行：
./run.sh configure --existing
./run.sh start该操作只创建启动配置，明确引用原环境文件中的单一 DATABASE_URL 字面量，不执行shell、不复制连接口令、不生成替代密钥。它保守选择保留的v0.5.1二进制和同版前端，避免把原schema6数据库直接迁移到开发版。已有启动配置不会被覆盖；其他目录或版本组合须手工核对后填写。配置中的 databaseEnvFile 与 databaseUrlFile 互斥，均不自动扫描或推测其他数据库。
已有数据库必须使用其原配套平台密钥。将配置的 key 设置为原密钥的绝对路径；如复用原二进制/前端，也可以分别配置 binary 和 web。不要对已有数据库运行空库初始化，也不要生成新密钥替代旧密钥，否则历史签名/加密结果无法由新密钥正常处理。start 在密钥缺失时直接拒绝，不自动创建替代密钥。
原本手动运行的实例需先由原启动方式妥善停止，再由本脚本启动；这一步可能涉及备份或维护窗口，本次开发没有替你停止或迁移原实例。
构建与更新
build 创建 .runtime/launcher/releases/<版本目录>，成功后原子切换 current 链接；旧构建不删除，运行中的进程仍使用原路径。现有 web/node_modules 可只读复用于私有构建；缺失时在私有目录执行 npm ci，不自动修改原前端依赖目录。
./run.sh build
# 已备份数据库和原密钥，确认可接受的迁移/维护窗口后：
./run.sh restart平台启动会执行源码定义的数据库迁移，因此业务升级前必须备份数据库及配套密钥。回退可在配置里指定上一版本的私有 binary 和 web，但旧二进制不等于数据库自动回退；数据库不兼容时需按已演练的恢复方案操作。详见运行与备份。
Docker 正式部署：新安装
此处提供单主机Compose部署。正式服务器需要 Docker Engine 和 Compose v2（建议2.20+），以及 Python 3.9+。它启动 PostgreSQL、平台和可选Caddy代理，不在宿主机启动原生平台。
./run.sh docker setup
# 编辑 .runtime/deploy/compose.env，填入实际域名和空闲宿主端口
./run.sh docker build
./run.sh docker start
./run.sh docker init --email admin@your-company.com
./run.sh docker statussetup 只生成缺失秘密，保留已有值，不输出密码。生成目录 .runtime/deploy 为0700；只读绑定的秘密文件为0444，让非root容器读取，宿主机其他普通用户不能穿过父目录访问。初始管理员密码在该目录的 bootstrap-password，只交给指定管理员；网页首次登录是否要求改密，以对应版本的凭据流程为准。
公开配置示例：
PUBLIC_ORIGIN=https://data.your-company.com
PUBLIC_HOST=data.your-company.com
DATANOUS_HTTP_PORT=8090
DATANOUS_IMAGE=datanous:0.5.2-dev- 使用内置Caddy时，
PUBLIC_HOST与 HTTPS 来源域名相同，服务器开放80/443并正确设置域名解析。脚本按该字段自动启用tlsprofile。 - 已有Nginx/Caddy网关时，
PUBLIC_HOST=留空；反向代理转发到127.0.0.1:宿主端口，仍将PUBLIC_ORIGIN设置为用户访问的HTTPS来源。 DATANOUS_HTTP_PORT仅绑定宿主机回环。若旧实例占用8090，选择其他空闲端口，不停止旧实例。- 本地容器测试可使用
PUBLIC_ORIGIN=http://127.0.0.1:18199、PUBLIC_HOST=，不把HTTP测试当作正式TLS验收。 compose.env只接受公开字段的KEY=VALUE，不执行shell；环境变量优先于文件。示例域名未修改时拒绝启动。
start 使用Compose的 up -d --wait，等待数据库和平台健康；Caddy证书、真实域名、代理及业务可用性仍需从外部实际访问验证。Compose的健康依赖与就绪等待语义参见官方说明。
数据、账号与日常启停
PostgreSQL数据、平台状态/签名密钥和Caddy状态分别保存于命名卷。新安装使用独立 datanous_admin 数据库管理账号；平台 datanous 账号是业务库owner，允许本库迁移，但不是超级用户，不具备创建数据库、角色、复制或绕过RLS权限。两个数据库秘密分开保存，平台容器只挂载业务连接文件。
./run.sh docker status
./run.sh docker logs
./run.sh docker restart
./run.sh docker stop
./run.sh docker startstop 保留容器及命名卷，脚本不提供删卷命令。restart 重启现有容器，不能代替重新构建或应用配置变更；更新源码/配置后，在完成备份和迁移评估后执行 docker build、docker start。不要把 down -v 或删除命名卷当作重启、升级或修复步骤。Compose项目名保留为 datanous，不要随意改名导致误挂新空卷。
已有容器部署与升级
数据库角色初始化脚本只在空数据卷首次安装时运行。已有卷不会因修改 POSTGRES_USER 或重新生成秘密而更改数据库角色/口令。旧版使用 datanous 超级用户的实例，不会自动降权；本轮没有迁移现有卷，也没有自动修改真实数据库账号。升级前应核对原数据库账号、实际口令、卷名及平台密钥，制定显式角色迁移方案；不要删除数据卷重新安装来绕过差异。PostgreSQL主要版本升级同样不能直接更换镜像挂载旧数据目录。
正式环境应把 DATANOUS_IMAGE 换为自己发布并确认过的版本/摘要；按企业策略备份数据库、平台密钥、秘密目录和代理配置，并演练异地恢复。源代码自带密钥文件不会打入镜像；独立连接器、外部链/身份、隐私引擎等按产品选择另行部署。
本轮验证边界
已提供进程生命周期定向测试、真实平台+全新私有PostgreSQL的初始化/启停/重启演练、健康探针测试，以及隔离构建检查。开发机尚无可用Docker Engine；镜像构建、容器非root卷权限、TLS签发和正式服务器部署不能据此声称通过。仓库CI新增独立容器冒烟作业，待远端实际运行后再记录容器验收证据。