agentspace启动失败时服务不可用，需先通过health检查、日志分析（fatal/panic/failed to migrate）、数据卷挂载合法性（路径、权限、属主）、环境变量格式（database_url、jwt_secret_key）四步精准定位根因。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
AgentSpace平台启动失败时，服务无法进入可用状态，用户无法通过UI创建Agent、配置连接器或触发流程编排，所有后台任务调度与网关监听均处于停滞。
确认启动失败现象
登录部署服务器后，执行curl -s http://localhost:8000/health，若返回Connection refused或HTTP 503，且docker ps | grep agentspace无运行中容器，则判定为启动失败；此时不要直接重启容器，先查清是镜像拉取中断、端口被占，还是初始化脚本退出。
执行docker logs agentspace-web --tail 50，重点捕获以FATAL、panic:、failed to migrate开头的行——这些才是真实阻断点，不是“服务未响应”这种表层描述。
检查Docker数据卷挂载合法性
AgentSpace依赖两个命名卷：agentspace-config（存config.yaml和.env）与agentspace-data（存SQLite数据库及上传文件）。若挂载路径错误或权限不匹配，服务会在加载配置阶段静默崩溃。
运行docker volume inspect agentspace-config，确认Mountpoint字段指向的宿主机路径存在且可读；若输出报错Error: No such volume，说明docker-compose.yml中定义的卷未被创建，需先执行docker volume create agentspace-config agentspace-data。
进入挂载目录：ls -l $(docker volume inspect agentspace-config | jq -r '.[0].Mountpoint')，检查config.yaml是否为普通文件（而非符号链接），且属主为1001:1001（AgentSpace容器内默认UID/GID）；若属主为root，执行chown -R 1001:1001 /var/lib/docker/volumes/agentspace-config/_data，否则容器启动时因权限拒绝读取配置而退出。
验证环境变量与配置一致性
AgentSpace在启动时会校验.env中关键变量是否满足格式要求，任意一项不合法即终止初始化。打开$(docker volume inspect agentspace-config | jq -r '.[0].Mountpoint')/.env，逐项核对：
方法一：检查DATABASE_URL是否为sqlite:///data/app.db或postgresql://user:pass@db:5432/agentspace格式；若写成sqlite:////data/app.db（多一个斜杠），SQLite驱动将解析失败并抛出Invalid URL异常。
方法二：确认JWT_SECRET_KEY长度≥32字符，且不含换行或制表符；用tr -d '\n\t' 验证值部分长度，小于32会导致加密模块panic。
【必须操作】修改任何配置后，必须删除旧容器并重建：docker rm -f agentspace-web && docker-compose up -d；仅执行docker restart不会重载.env变更。
排查多容器网络通信阻断
AgentSpace由web、api、worker、redis四容器组成，启动失败常因worker无法连上redis或api无法访问数据库。先确认网络就绪：
第一步：运行docker network inspect agentspace_default，检查所有容器是否出现在Containers列表中；若缺失agentspace-redis-1，说明redis容器启动失败，应单独查看其日志：docker logs agentspace-redis-1。
第二步：若redis正常，进入web容器调试连通性：docker exec -it agentspace-web sh -c "apk add --no-cache curl && curl -v http://redis:6379"；若返回Connection refused，检查docker-compose.yml中redis服务是否声明了ports: ["6379:6379"]——该行会导致宿主机端口暴露，反而干扰内部DNS解析，必须删掉。
第三步：强制刷新服务发现缓存：docker-compose down && docker-compose up -d --force-recreate；此操作重建所有容器网络栈，解决bridge网络下DNS缓存陈旧导致的redis: Name does not resolve问题。
