企业官网建设流程全解析

Cloud in a Bottle是一个让你在自己服务器上部署、使用和分享 Web 应用的开源平台——应用、数据和基础设施都归你掌控。本文整理了一份7 类常见问题的故障排查清单，并附上每个问题对应的日志位置和排查命令速查表，帮助新手快速定位故障、恢复实例。

先搞清楚：日志在哪里？

排查任何问题前，先知道日志分四类存放（详见 docs/src/how_it_works/logs.md）：

关键路径速记（数据目录一般为~/.openhost/local_compute_space/）：

• Router 日志文件：persistent_data/openhost/compute_space.log
• 应用日志目录：temporary_data/app_temp_data/<app>/
• 完整目录结构见 docs/src/how_it_works/overview.md

📋 7 类常见问题速查表

官方调试指南：docs/src/operation/debugging.md

1️⃣ Dashboard 打不开：先查 openhost 服务

Cloud in a Bottle 以单个 systemd 单元openhost运行（Caddy 和 CoreDNS 都是它的子进程）。第一步永远是：

sudo systemctl status openhost # 看服务状态和最后几行日志 sudo journalctl -u openhost -n 200 # 看最近 200 行日志 sudo systemctl restart openhost # 确认是配置问题后重启

💡 因为 journald 日志在重启后仍然保留，服务起不来时的报错只有在这里能看到。配置修改后需要重启才生效。

2️⃣ 应用构建失败：看构建日志的前半段

bottle app logs <app>会先输出podman build的构建日志，再跟容器日志——构建阶段的报错都在前半段。Dashboard 的应用详情页也能看到同样的内容。每次重新构建时，旧构建日志会带时间戳归档（保留最近 5 份）。

3️⃣ 应用反复死亡：多半是内存不够

容器默认内存上限只有128 MB（manifest 中的memory_mb，见 docs/src/creating_an_app/manifest_spec.md）。应用一启动就被 OOM 杀掉、反复重启是典型症状。Router 内置的 memory_guard.py 会在内存接近上限或发生 OOM 时写入告警日志。解决办法：在 manifest 中调大memory_mb，或降低应用自身的内存消耗。

4️⃣ 构建成功却 502：检查端口绑定

502 表示 Router 代理到了容器，但容器内没有进程在监听端口。用bottle app logs <app>查看应用自身的报错，确认它监听的就是cloudinabottle.toml中port字段声明的端口，并且监听在 0.0.0.0 而非仅 localhost。

5️⃣ 应用被自动停掉：磁盘空间守卫在保护你

当磁盘可用空间低于阈值storage_min_free_mb（默认500 MB）时，存储守卫 会主动停掉运行中的应用，防止磁盘写满拖垮整个实例。排查思路：

1. 用df -h或 Dashboard 的 System info 页确认磁盘占用
2. 清理数据（可以在 System 页临时暂停守卫，启动一个文件浏览应用来清理）
3. 必要时调大阈值或设为0关闭守卫（config.py），然后重启服务

6️⃣ 域名没有证书：DNS 委派 + 证书申请日志

公共域名的证书通过ACME DNS-01申请：实例会把挑战 TXT 记录写进自己的 CoreDNS 区域，CA 读取后删除。所以前提是整个 zone 已经委派给这台机器（而不是简单指一条 A 记录），详见 docs/src/how_it_works/routing.md。

排查方法：在证书申请期间执行journalctl -u openhost -f观察全过程。证书下发前，域名会以 Caddy 自签名证书提供服务（浏览器会有警告）——这是正常的中间状态。

7️⃣ 忘记 owner 密码：SSH 直接重置

owner 密码以 bcrypt 哈希存在 Router 的 SQLite 数据库里，没有重置链接。只要能 SSH 进机器，就可用 debugging.md 中的方法直接更新users表的password_hash，无需重启，下次登录即生效。完成后记得吊销不认识的 API token。

🔧 两个万能排查工具

JSON 诊断包——一条命令打包实例（或单个应用）的完整状态，可以直接贴给开发者或 AI 助手：

bottle diagnostics # 整个实例 bottle app diagnostics <app> # 单个应用

其收集逻辑见 diagnostics.py。

网页终端——SSH 没配好时的最快入口，直接访问https://<你的域名>/terminal/；进应用容器用bottle app ssh <app>。完整命令参考 docs/src/operation/cli.md。

🏁 排查流程总结

按这个顺序走，能解决 90% 的问题：

1. sudo systemctl status openhost—— 服务活着吗？
2. bottle logs/journalctl -u openhost -f—— Router 侧报了什么？
3. bottle app logs <app>—— 应用构建和运行侧报了什么？
4. bottle diagnostics—— 打包全量状态交给开发者
5. 确认磁盘与内存余量 —— 存储守卫和内存上限是隐形杀手

掌握这份 故障排查清单 和日志位置速查表，你的 Cloud in a Bottle 实例就能快速从大多数故障中恢复，继续安心托管你的应用。