Superalgos / 运行与排错
Superalgos 排错：先看日志，再对症下药
这套系统有五个独立应用（平台、任务、网络、社交交易、仪表盘），每个应用都有自己的日志目录；出问题时官方的第一步不是改代码，而是去 Platform/My-Log-Files 下按应用与日期找日志。这一页把日志位置、四类常见故障的核对方式，以及官方指定的求助渠道整理成表——顺序错了会在无关的地方耗掉大量时间。
Superalgos 日志怎么看：目录结构与详细度开关
官方把各应用的日志统一到同一个 logger，并说明了目录约定。知道这套约定，比背报错信息更有用。
| 项目 | 官方约定 | 你要找的东西 | 注意点 |
|---|---|---|---|
| 日志根目录 | 默认 ./Platform/My-Log-Files，也可以自定目录 | 所有应用的日志都在其下按应用分目录 | 容器化部署时要把它挂成卷，否则重启即丢 |
| 应用子目录 | Dashboards / Network / Platform / Tasks / SocialTrading 各一个 | 先确定是哪一层出问题，再进对应目录 | 不要只翻 Platform，网络与任务的问题在别的目录 |
| 日志类型 | 每个应用下有 error 与 combined 两个子目录 | error 快速看失败，combined 看上下文 | 两者都按日期分文件（%DATE%.log） |
| 任务日志 | Tasks 目录下再按 <TASK_ID> 分目录，各自带 error 与 combined | 多任务并行时先锁定哪个任务失败 | 任务 ID 与界面上看到的一致 |
| 日志格式 | 带时间戳、级别与来源标记，例如 2023-01-31T16:44:06.513Z | info | SA | ... | 时间戳用于对齐你操作的时间点 | 命令行输出与文件输出字段略有差异 |
| 调整详细度 | 启动命令加 logLevel，取值 debug / info / warn / error；也支持写成 profile 配置 | 只加一个级别，更严重的都会记录 | debug 会同时写入文件，官方认为这通常是开发者在临时使用 |
| 默认级别 | info | 日常排错从默认级别开始就够 | 改完记得改回来，debug 会显著增大日志体积 |
Superalgos 依赖安装类故障
发生在 node setup 与 node setupPlugins 阶段的问题，官方在 README 的 Troubleshooting 附录里逐条给了处理方向。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 大量意料之外的错误 | 本地 npm 状态与项目锁文件不一致 | 看报错是否集中在依赖解析阶段 | 官方建议先跑 npm ci --omit=optional 重置，再重跑 node setup |
| 提示版本过低 | npm < 5 或 node，官方要求 node > 16.6 | node -v / npm -v | 升级 Node；发行版自带版本偏旧时用 nvm 装新版 |
| 权限被拒 | 安装在受系统保护的目录 | 确认目录是否需要管理员权限 | Windows 用管理员命令行；Linux/macOS 用 sudo node setup |
| 命令找不到 | Windows 下 C:\Windows\System32 不在全局 PATH | 检查系统 PATH | 按官方提示把该目录加回 PATH |
| 缺 make / cc / gcc | 非 x86 芯片（如 arm64）需要额外构建工具 | 看报错指向的缺失程序 | 安装 make、gcc、g++（Debian 系可装 build-essential） |
| 被提示跑 npm audit fix | 该提示对本项目不适用 | —— | 官方明确说忽略它，不要执行 |
| 装 TensorFlow 依赖最后报错 | Windows 上的已知边界情况 | 看报错后是否附有后续说明 | 按报错附带的说明处理；该集成官方自述部分且未完成 |
| 扩展仓库出问题 | 本地 Plugins 目录或你账号下的 fork 损坏 | 确认是哪个扩展目录报错 | 删掉对应扩展目录或删掉有问题的 fork，重跑 node setupPlugins 修复 |
Superalgos 启动不了或界面打不开怎么办
装完之后的故障大多集中在「服务起来了但访问不到」和「资源不够」。这两类都有明确的核对路径。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 界面打不开 | 服务未启动或浏览器地址不对 | 看终端是否显示服务已启动 | 确认访问端口为 34248；先等界面加载完（官方说需要几秒） |
| 用非 Chrome/Safari 时报错 | 官方只在 Chrome 与 macOS Safari 上测试 | 换到 Chrome 复现同一操作 | 先换浏览器确认；求助时说明浏览器，否则官方会先要求你在 Chrome 复现 |
| Docker 里界面打不开 | 端口未映射到宿主机 | docker ps 看端口映射 | 补 -p 34248:34248（以及 18041）后重建容器 |
| 容器日志报 git 缺失 | 官方刻意不在容器内装 git | 看报错是否只有这一条 | 官方说明不影响机器人运行，不要当故障修 |
| 保存工作区时报权限错 | 容器以固定 UID/GID 运行，挂载目录属主不匹配 | 看宿主机上 My-* 目录属主 | 调整目录属主/用户组，或在 compose 里指定运行用户 |
| 网络节点外部连不上 | websocket 端口（默认 18042）未放行 | 从外部机器测端口连通性 | 按官方说明放行端口，并把节点配置里的 host 填成正确 IP |
| 换了地方就打不开界面 | 远端部署时界面靠端口访问，而不是本地窗口 | 确认目标机器 IP 与端口 | 用 <机器IP>:34248 访问；无界面服务器启动时加 noBrowser |
| 多实例冲突 | 快捷方式名字冲突 | 看是否装了多个 Superalgos 目录 | 官方要求先重命名目录再执行建快捷方式 |
node platform [minMemo] [noBrowser] [项目] [工作区]——内存紧张加 minMemo，无界面服务器加 noBrowser，想直接进某个工作区就把项目和名字写在后。参数顺序以官方 README 为准。凭据与身份报错怎么办：网络类故障排查
这一类最容易误判成「Superalgos 程序坏了」，实际多数是「改动还没生效」或「引用指错了」。
| 现象 | 可能原因 | 核对方法 | 处理方向 |
|---|---|---|---|
| 报 Network Client Identity 不匹配 | 本地签名账户与治理扩展仓库里的账户不一致 | 比对本地档案与已合并扩展里的账户 | 用「Add specified User Profile」导入正确档案，补齐节点与引用后重新提交并等待 |
| 刚改完就报连不上 | 档案合并与被节点读取本身有约 10 分钟延迟 | 确认治理仓库里的改动是否已合并 | 等够窗口再验证，不要连续改第二次 |
| 扩展安装后仍缺东西 | setupPlugins 未执行完或新增扩展类型未补装 | 看 Plugins 目录是否缺对应子目录 | 重跑 node setupPlugins <用户名> <令牌>，脚本会补齐缺失的 fork 与 clone |
| 令牌相关的操作用不了 | 令牌权限不足或已失效 | 确认令牌是否含 repo 与 workflow 权限 | 按官方要求重新生成令牌；不要把令牌写进要外发的文件 |
| 存储写入失败 | 存储容器的 codeName、GitHub 账号或仓库名与凭据文件不一致 | 比对容器配置与 My-Secrets 里的条目 | 让两边写法完全一致后再试 |
| 用了测试网之后机器学习任务异常 | 官方已知问题：测试网当前与 ML 项目互相干扰 | 看是否同时跑了两类任务 | 官方称「本不该发生、看起来是 bug」；换网络或错开任务以规避 |
| 任务找不到可用服务器 | 任务未挂 Task Server 引用，或所指向的服务器不空闲 | 看任务节点上的引用指向 | 改指向档案里一个空闲的 Task Server |
My-Secrets 内容或带账号信息的截图发出去。官方在 README 里明确写了管理员不会主动私聊、也不会索要 API key、币或现金；任何以「帮你排查」为名索要凭据的都按诈骗处理。资源与性能：这台机器能跑 Superalgos 吗
官方在 README 与 troubleshooting 附录里给过几条量化提示，值得在建站前先对一遍。
| 资源项 | 官方口径 | 低于门槛时的现象 | 处理方向 |
|---|---|---|---|
| 内存 | 8 GB 及以下建议加 minMemo 启动 | 启动慢、界面卡顿 | 加上 minMemo；学习阶段尽量用内存充足的机器 |
| 极端低内存 | 官方说明仅 1 GB 内存的机器已基本跑不动，若要勉强用需退到 Node 16.x（18.x 在安装阶段就要超过 1 GB） | 安装或运行中卡死 | 不要用 1 GB 级设备边学边跑，先换机器 |
| 磁盘 | 仓库约 1.18 GB，还要放依赖、数据与日志 | clone 或安装中途失败 | 预留足够空间，并把日志与数据目录规划好 |
| 路径长度 | 官方建议装在盘根目录或较短的路径下 | 某些系统上安装报错 | 换短路径重装 |
| 网络 | 安装与运行都依赖网络；信号与机器学习还依赖节点端口可达 | 安装超时、拿不到测试用例 | 保持稳定连接，并确认 18042 等端口可用 |
| CPU/GPU | 机器学习测试客户端会长时间占用算力（单次训练从几分钟到数小时） | 机器长期高负载 | 规划好参与时间，或专门用一台机器跑 |
| 运行方式取舍 | 官方建议学习阶段在本机跑，极简硬件与远端部署留给准备实盘的阶段 | 没有图形界面时上手难度陡增 | 先本机学会，再迁到生产环境 |
遇到问题去哪求助：官方渠道与提问规范
官方在 README 里明确说了「安装出问题不要开 issue」，也说明支持由志愿者提供。按它的规范提问，得到回复的概率会高很多。
| 情况 | 官方指定渠道 | 为什么 | 提问时要带什么 |
|---|---|---|---|
| 安装或首次运行失败 | Support Telegram 群（README 里给出链接，并附有置顶消息的操作说明） | 官方明确要求这类问题不要开 issue | 按置顶消息的指引提供信息 |
| 想要更社区化的讨论 | 官方 Discord 服务器 | 官方提示 Discord 的响应时间通常更长 | 同样附足上下文 |
| 机器学习相关 | 官方文档提到有专门的 Machine Learning 群，并有测试客户端目录内的说明 | 这块的排错与普通安装不同 | 说明你跑到哪一步、报什么错 |
| 系统运维/部署 | 官方文档提到有面向系统管理员的群 | 容器与网络节点问题更偏运维 | 附部署方式、端口与日志片段 |
| 代码缺陷或功能请求 | 仓库 issue 区 | 这才是 issue 的用途 | 附复现步骤、版本与日志 |
| 通用提问原则 | 官方说明支持由志愿者提供 | 信息不全的问题很难被处理 | 建议一次给齐：操作系统、Node/npm 版本、安装路径、执行的命令、完整报错、对应日志文件 |
| 不要做的事 | 不要把令牌、账号、My-Secrets 内容或含个人信息的截图发到任何公开渠道 | 公开渠道会被索引与转发 | 需要贴日志时先脱敏 |
排错常见问题
日志约定与参数以官方 README、Logging 文档与各子 README 为准；本站未实机复现这些报错。
出问题第一件事做什么？
按官方约定先看日志：默认在 ./Platform/My-Log-Files 下，按应用（Platform / Tasks / Network / SocialTrading / Dashboards）分目录，每个应用下有 error 与 combined 两类按日期命名的文件。先确认是哪一层报错，再去对应目录找当天的文件，比反复重装有效得多。
怎么让日志更详细？
启动时加 logLevel 参数，取值 debug / info / warn / error，只写一个级别、更严重的都会记录；默认是 info。官方说明 debug 会同时写入文件，通常是开发者在临时排查时使用。排查完记得调回默认级别，否则日志会迅速变大。
界面打不开是端口问题吗？
先确认服务是否已启动，再确认访问端口是 34248；如果跑在另一台机器或容器里，要从宿主机或局域网用「机器 IP:34248」访问，容器还需要把端口映射出来。官方也提示界面加载需要几秒，别刚启动就判断失败。
node setup 报一堆错怎么办？
官方的兜底建议是先用 npm ci --omit=optional 重置本地依赖状态，再重跑 node setup。同时确认 Node 版本满足要求（官方口径是 node > 16.6、npm > 5），以及安装目录是否需要管理员权限。Linux 上如果看到提示跑 npm audit fix，官方明确说忽略它。
改了配置要等多久才生效？
涉及 User Profile 的改动不是本地立即生效，而是要经过治理仓库合并，官方提示约 10 分钟后才会被运行中的网络节点读取。因此刚改完就报连接或身份类错误时，先等够这个窗口，再按排错表核对，可以少走很多弯路。
为什么官方说安装问题不要开 issue？
因为 README 把安装类问题指向了 Support Telegram 群，并说明在线支持由志愿者提供、Discord 响应会更慢。按官方规范提问能显著提高被回复的概率：一次给齐操作系统、Node/npm 版本、安装路径、执行的命令、完整报错与对应日志文件。
把日志发到群里安全吗？
要小心。日志里可能包含你的本地路径、账号名甚至配置片段，公开发布后可能被索引。建议先脱敏：去掉本地用户名与路径、去掉令牌与账号信息，只保留与报错相关的片段。任何情况下都不要发送 My-Secrets 里的内容。
实在不想折腾环境，有别的路吗？
如果当前目标只是拿到行情、指标或研究结论，可以先用免部署的 EasyClaw 技能路线（本机已核验 akshare-finance、quant-analyst、chart-image 等）；但它不是 Superalgos 的替代部署方式，也不能跑交易机器人，两者没有已证实集成。入口在顶部导航「对比」。