后端部署与实机连接

1.4 中文深色界面与分级菜单

已按用户提供的参考图改为黑色背景和深灰分层界面。新增观测概览；主控台、设备和序列采用分级菜单，不再集中在一个长页面。中文正文 16px，375 / 390 / 430px 布局与底部导航经过截图复查。设计与信息主次见 docs/UI-DESIGN.md。

分体部署更新到 nina-server-1.4.zip 和 nina-host-1.4.zip，两端同时升级并保留 config.json 与运行数据。域名仍为 https://nina.finderskys.online，现有密钥不变。

1.3 主控台与图形化序列

新增“主控台 / Imaging”页面和多目标图形化序列生成器，继续分为服务器与工控机两个部署包，域名及现有密钥保留。详见 docs/IMAGING.md，其中按 NINA 源码列出已接入功能及 Advanced API 未开放的项目。

支持图像预览、历史与统计、解析、导星曲线、设备附加控制，及常用顺序序列的可视化编排、生成、保存、加载。生成与加载不会自动开始拍摄。

此版不是完整 NINA 桌面克隆，也不冒充支持插件全部节点；未接入项在功能对照中明确列出。

1.2 分体部署与实际拍摄入口

本次正式部署交付为两个包：nina-server-1.2.zip 和 nina-host-1.2.zip，服务器域名已配置为 https://nina.finderskys.online。两个包内 README 分别说明部署操作；详见随包交付的《部署与拍摄说明.md》。

服务器端仅运行转发和网页，工控机端运行 Agent，主动通过 HTTPS 连接服务器；NINA 与 PHD2 保持本机访问。两端保留当前项目的同一对密钥。

新增序列页拍摄监控，每 5 秒读取真实设备和序列状态；可按名称读取、加载 NINA 保存的序列，再单独开始。连续拍摄由 NINA 本地执行，原图保存工控机。

新增只读检查命令 python -m nina_control.preflight --config config.json 和 Windows 当前用户登录任务脚本 install-agent-task.ps1。不自动安装登录任务。

停止命令有独立执行名额，避免四个远程查询或操作等待时阻塞停止。停止序列、曝光、导星和赤道仪是独立命令。

HTTP 命令成功表示 NINA 接受或完成了相应 API 请求，不能用单帧曝光 API 的成功或 IsExposing=false 证明图像已落盘；首次拍摄需要核对 NINA 保存目录中的文件。

该版本未在你的远程服务器或真实设备上验收；Docker、HTTPS 证书签发和真实出片仍需部署后检查。序列 JSON 编辑沿用原生格式，未提供完整拖拽编辑器或原图云端上传下载。

启动失败时

新版 start.ps1 会验证 Python 3.11+ 是否能实际运行，并检查 sqlite3、ssl 和后端模块。首次配置直接由 PowerShell 生成，已有 config.json 不覆盖、不更换密钥。支持 Windows PowerShell 5.1，以及中文和含空格的解压路径。

如果旧版本提示 Configuration initialization failed，替换新版 start.ps1 后重新双击原来的启动 CMD。若新版提示没有可用 Python，请安装 Python 3.12 后重开启动脚本；可使用 winget install --exact --id Python.Python.3.12，或从 https://www.python.org/downloads/windows/ 安装。

可仅检查环境而不启动服务：powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\start.ps1 -CheckOnly。若 Python 安装在自定义路径，用 -Python C:\Python312\python.exe 指定。发生失败时保留原始 Python 错误，不再只显示配置初始化失败。

后端是 nina_control/ 中的 Python 服务，网页由同一个服务提供，无需单独部署前端。只需 Python 3.11 或更高版本，不需要 pip 安装包。服务器和工控机可以使用同一份代码，以不同启动模式运行。

先在工控机上直接使用

1. 将整个 nina-control 目录放到安装 NINA 的 Windows 工控机。

2. 双击 start-host.cmd。会启动真实 NINA 的本机后端与测试网页，默认端口 18700。没有配置时只在首次自动生成 config.json，已有密钥不会更换。

3. 打开 http://127.0.0.1:18700，连接设置填写 config.json 的 api_token，点击“连接”。网页会记住密钥。

4. 启动 NINA，在插件页面安装/启用 Advanced API 并按插件要求重启 NINA。确认 http://127.0.0.1:1888/v2/api/version 能返回 JSON。

5. 在 NINA 选择你的真实 ASCOM 赤道仪驱动，设置串口/设备连接参数。可先在 NINA 连接，也可在网页点击“连接赤道仪”，它连接 NINA 已选定的驱动，不自动替你选驱动或串口。

6. 在 NINA 至少打开一次构图助手，配置相机尺寸、像元和望远镜焦距。网页查询目标，读取视场，点击 Goto 开始指向并开启跟踪。

现在网页不再因为缓存状态为离线、停放或未连接而禁用连接、停止和已选目标的 Goto。实际请求会发送给后端；若 NINA 未启动、设备停放或驱动拒绝，执行记录显示真实错误。Goto 仍要求选中一个目标，执行期间防止重复提交。

上述 host 模式已经包含后端，不需要另起 server。关闭终端会关闭服务；再次双击即可重启，密钥保留。

服务器与工控机分开部署

连接结构：浏览器 → 服务器 18700 → 工控机主动领取命令 → 本机 NINA 1888。

服务器端

1. 将代码复制到服务器。Windows 双击 start-server.cmd；Linux 在项目目录执行：

python3 -m nina_control.configure --config config.json --allowed-host astro.example.com
python3 -m nina_control server --config config.json --bind 127.0.0.1 --port 18700

这里的域名必须替换为你的实际域名。第一次生成的 config.json 含 api_token、agent_token，后续重复 configure 会保留这两个值。

2. 用已有 HTTPS 反向代理将域名转发至 127.0.0.1:18700。需要保留 Host；config.json 的 allowed_hosts 包含访问域名。以下是可直接调整域名使用的 Caddyfile：

astro.example.com {
    reverse_proxy 127.0.0.1:18700
}

3. 打开 https://astro.example.com/health，应返回 ok=true。此时仅表示服务器启动，设备要等 Agent 连接。

工控机端

1. 复制同一份代码到安装 NINA 的工控机。把服务器 config.json 中的 api_token、agent_token 原值复制到工控机 config.json；两端必须一致，不要在两台机器独立生成不同密钥后直接启动。

2. 修改工控机 config.json：

{
  "api_token": "与服务器相同的api_token",
  "agent_token": "与服务器相同的agent_token",
  "server_url": "https://astro.example.com",
  "backend": "nina",
  "nina_url": "http://127.0.0.1:1888/v2/api",
  "nina_axis_url": "ws://127.0.0.1:1888/v2/mount",
  "catalog_path": "C:/Users/你的Windows用户名/AppData/Local/NINA/NINA.sqlite"
}

示例里的密钥占位符不能直接使用；填配置生成的两个不同值，各至少 32 字符。catalog_path 使用工控机实际路径。server_url 使用服务器真实 HTTPS 域名，不能填写工控机自己的 localhost。

3. 双击 start-agent.cmd。Agent 主动连接服务器，不需要在工控机路由器映射端口。Agent 本机调试页为 http://127.0.0.1:18701。

4. 浏览器打开服务器域名，填 api_token；状态里出现工控机/赤道仪信息。之后由用户执行连接、查询和 Goto。

同一台工控机用 host 或 agent 任选一种模式，不要为同一设备同时启动多个控制实例。需要单机改双端时，先关闭 host 终端，再启动 agent。

Linux 服务器用 Docker 部署

项目自带 Dockerfile 和 compose.yaml，仅用于平台服务器；NINA 和 Agent 仍在 Windows 工控机运行。

先准备真实 config.json：可从 Windows 已生成配置复制，保留密钥并将服务器域名加入 allowed_hosts。然后在代码目录执行：

docker compose up -d --build
docker compose logs -f server

服务只映射服务器环回 18700，HTTPS 反向代理仍按上一节配置。SQLite 数据保存在 nina-data 卷；配置只读挂载，不会写进镜像。

本环境未安装/运行 Docker，本交付已验证 Python 双端和本机 HTTP 流程；Docker 镜像需在你的目标服务器实际构建验证。

如何确认每一段正常

当前设备驱动的实机运动还需由你连接后验证。工控机客户端从不模拟设备，无法连接时会返回明确错误。

升级到设备与序列扩展版

先关闭后端终端，再用新版文件覆盖旧版代码。保留 config.json 和整个 .runtime 目录，密钥与序列库不会被更换。单机仍运行 start-host.cmd，双端仍运行 start-server.cmd / start-agent.cmd，两端代码均需更新。浏览器按 Ctrl+F5 刷新后可见设备控制、序列管理页面。

主相机、滤镜轮和电调焦先在 NINA 选择正确驱动。导星相机在 PHD2 选择真实相机，并启用工具 → 启用服务器；默认端口 4400，NINA 的 guider 选择对应 PHD2 实例。不要把同一个相机同时作为主相机和 PHD2 导星相机连接。

序列库默认 .runtime/sequences，使用 Agent 时位于工控机。NINA 高级序列器需先打开一次。网页可导入 NINA 保存的高级序列 JSON，保存到库后点击加载，再显式开始。