跳转至

服务器启动总结

会话概览

日期: 2026-03-25 任务: 启动智桥服务器并完成技术债务第4项（移除硬编码localhost）

✅ 完成的工作

1. 移除硬编码 localhost 引用

修改的文件: - relay-server/config.py - 添加 ws_host 配置项 - relay-server/server.py:177 - 更新主机显示逻辑 - relay-server/health_check.py:390-395 - 更新打印语句 - relay-server/chat_server.py - 更新为使用配置 - web/ui/index.html - 添加配置脚本 - web/ui/js/settings.ts - 更新为读取配置 - .gitignore - 添加 web/ui/config/config.js - .dockerignore - 添加 web/ui/config/config.js

创建的文件: - web/ui/config/config.js.example - 前端配置示例

2. 创建配置文档和演示

文档文件 (5个): 1. CONFIG_DEMO_INDEX.md - 演示文档主索引 2. CONFIG_QUICK_REFERENCE.md - 30秒快速参考 3. CONFIGURATION_GUIDE.md - 完整配置指南 4. LOCALHOST_REMOVAL_SUMMARY.md - 技术实现总结 5. DEMO_SUMMARY.md - 演示文档总结

演示脚本 (4个): 1. demo_default_config.sh - 默认配置演示 2. demo_env_config.sh - 环境变量演示 3. demo_frontend_config.sh - 前端配置演示 4. demo_production_config.sh - 生产配置演示

启动脚本 (1个): - start_servers.sh - 统一服务器启动脚本

3. 修复启动问题

问题及解决方案:

问题 解决方案
缺少 cachetools 依赖 安装 pip3 install --break-system-packages cachetools
异步方法调用错误 修改 len(self.manager.list_tools()) 为 len(self.manager.tools)
路由方法错误 确认使用 add_put() 和 add_delete()
变量作用域错误 将 cleanup_task 初始化移到 try 块之前
端口被占用 添加自动检查和端口释放逻辑

修改的文件: - relay-server/server.py:112 - 修复异步调用 - relay-server/http_server.py:56,57 - 确认路由方法正确 - relay-server/start_server.py:109-130 - 修复变量作用域

🚀 服务器状态

当前运行的服务

WebSocket 中继服务器: - 监听地址: 0.0.0.0:8765 - 客户端连接: ws://localhost:8765 - 进程 PID: 2953247 - 状态: ✅ 运行中

HTTP 健康检查服务器: - 监听地址: 0.0.0.0:8000 - 访问地址: http://localhost:8000 - 进程 PID: 2953474 - 状态: ✅ 运行中

访问地址

服务 地址
Web UI http://localhost:8000/web/ui/index.html
健康检查 http://localhost:8000/health
服务状态 http://localhost:8000/status
指标 http://localhost:8000/metrics
API 文档 http://localhost:8000/docs
WebSocket ws://localhost:8765

当前配置

服务器配置: 

{
  "host": "0.0.0.0",
  "port": 8765,
  "ws_host": "localhost",
  "max_connections": 100,
  "enable_wss": false
}

安全配置: 

{
  "enable_auth": false,
  "enable_rate_limit": true,
  "enable_csrf_protection": true
}

会话管理: - 工具数量: 8 - 临时目录: /home/ai/.zhineng-bridge/tmp - 会话超时: 3600 秒

📚 文档结构

配置系统文档

zhineng-bridge/
├── CONFIG_DEMO_INDEX.md          # 演示文档主索引 ⭐
├── CONFIG_QUICK_REFERENCE.md     # 快速参考卡片
├── CONFIGURATION_GUIDE.md        # 完整配置指南
├── LOCALHOST_REMOVAL_SUMMARY.md # 技术实现总结
├── DEMO_SUMMARY.md             # 演示文档总结
│
├── demo_default_config.sh        # 默认配置演示
├── demo_env_config.sh            # 环境变量演示
├── demo_frontend_config.sh       # 前端配置演示
└── demo_production_config.sh     # 生产配置演示

使用流程

  1. 初次使用者 (5分钟):
  2. 阅读 CONFIG_QUICK_REFERENCE.md
  3. 运行 ./demo_default_config.sh

  4. 访问 Web UI

  5. 开发者 (20分钟):

  6. 阅读 CONFIGURATION_GUIDE.md
  7. 运行所有演示脚本

  8. 自定义配置

  9. 生产部署 (40分钟):

  10. 阅读 docs/PRODUCTION_DEPLOYMENT.md
  11. 阅读 CONFIGURATION_GUIDE.md
  12. 运行 ./demo_production_config.sh
  13. 部署到生产环境

🛠️ 管理命令

启动服务器

统一启动脚本 (推荐): 

./start_servers.sh

手动启动: 

# WebSocket 服务器
python3 relay-server/start_server.py

# HTTP 服务器
python3 relay-server/health_check.py

停止服务器

使用启动脚本: 

# Ctrl+C 会自动停止所有服务器

手动停止: 

kill $(cat .ws_server.pid)
kill $(cat .http_server.pid)

查看状态

检查端口: 

lsof -i :8765
lsof -i :8000

测试端点: 

python3 -c "
import urllib.request
import json
response = urllib.request.urlopen('http://localhost:8000/status')
print(json.dumps(json.loads(response.read().decode()), indent=2))
"

⚙️ 配置示例

开发环境

默认配置（无需修改）: 

# 直接启动
./start_servers.sh

生产环境

使用环境变量: 

export ZHINENG_BRIDGE_WS_HOST="api.example.com"
export ZHINENG_BRIDGE_SECURITY_SECRET_KEY="your-secret-key"
export ZHINENG_BRIDGE_ENABLE_WSS="true"
./start_servers.sh

使用配置文件: 

# 创建 .env.prod
cat > .env.prod << 'EOF'
ZHINENG_BRIDGE_WS_HOST=api.example.com
ZHINENG_BRIDGE_SERVER_PORT=8765
ZHINENG_BRIDGE_SECURITY_SECRET_KEY=your-secret-key
ZHINENG_BRIDGE_ENABLE_WSS=true
ZHINENG_BRIDGE_CERT_FILE=/path/to/cert.pem
ZHINENG_BRIDGE_KEY_FILE=/path/to/key.pem
EOF

# 启动
source .env.prod && ./start_servers.sh

前端配置: 

# 创建 web/ui/config/config.js
cat > web/ui/config/config.js << 'EOF'
window.ZHINENG_BRIDGE_CONFIG = {
    WS_HOST: 'api.example.com',
    WS_PORT: 8765,
    THEME: 'light',
    LANGUAGE: 'zh-CN'
};
EOF

🎯 技术债务进度

已完成 (4/6)

  1. ✅ 测试部署配置
  2. 验证脚本语法正确
  3. 验证 docker-compose 配置

  4. Docker 构建成功

  5. ✅ 移除默认管理密码

  6. 修改 scripts/init_auth_db.py
  7. 修改 relay-server/start_server.py

  8. 使用 secrets.token_urlsafe(16) 生成随机密码

  9. ✅ 完成空实现

  10. 实现 cleanup_inactive_clients() 方法
  11. 添加 last_activity 跟踪

  12. 在 is_allowed() 中更新活动时间

  13. ✅ 移除硬编码 localhost 引用

  14. 添加 ws_host 配置项
  15. 更新所有相关代码
  16. 创建配置文档和演示脚本

待完成 (2/6)

  1. ⏳ 添加缺失的测试
  2. 创建 Storage 模块测试
  3. 创建 Encryption 模块测试
  4. 创建前端 JavaScript 测试

  5. 修复 E2E 测试

  6. ⏳ 改进文档

  7. 替换占位符邮箱
  8. 完成不完整部分
  9. 更新 Node.js 版本要求
  10. 创建 quickstart.sh 脚本

🔍 验证测试

服务器验证

✅ WebSocket 服务器: - 监听在 0.0.0.0:8765 - 端口可访问 - 配置正确加载

✅ HTTP 服务器: - 监听在 0.0.0.0:8000 - /status 端点正常 - 配置正确显示

配置验证

✅ 默认配置: - ws_host: localhost - port: 8765 - 正确加载

✅ 环境变量覆盖: - ZHINENG_BRIDGE_WS_HOST 生效 - 配置正确更新

功能验证

✅ 8种 AI 工具已注册 ✅ Session Manager 初始化成功 ✅ Rate limiter 初始化成功 ✅ User database 初始化成功

📝 注意事项

开发环境

⚠️ 当前配置为开发环境：

  1. 未设置 SECRET_KEY
  2. 生产环境必须设置

  3. 使用: export ZHINENG_BRIDGE_SECURITY_SECRET_KEY="..."

  4. 认证未启用

  5. 生产环境建议启用

  6. 使用: export ZHINENG_BRIDGE_SECURITY_ENABLE_AUTH=true

  7. 未启用 HTTPS/WSS

  8. 生产环境建议启用
  9. 使用: export ZHINENG_BRIDGE_ENABLE_WSS=true

部署前检查清单

  • [ ] 设置 ZHINENG_BRIDGE_SECURITY_SECRET_KEY
  • [ ] 启用认证 (enable_auth=true)
  • [ ] 配置 HTTPS/WSS 证书
  • [ ] 更新 ZHINENG_BRIDGE_WS_HOST 为生产地址
  • [ ] 配置数据库 (PostgreSQL/MySQL)
  • [ ] 设置日志级别为 INFO 或 WARNING
  • [ ] 启用 Prometheus 监控
  • [ ] 配置备份策略

🚀 下一步

立即可用

  1. 访问 Web UI

  2. 打开浏览器: http://localhost:8000/web/ui/index.html

  3. 测试 WebSocket 连接

  4. 连接: ws://localhost:8765

  5. 发送测试消息

  6. 查看 API 文档

  7. 访问: http://localhost:8000/docs

学习资源

  1. 配置系统
  2. 阅读 CONFIG_QUICK_REFERENCE.md
  3. 运行演示脚本

  4. 尝试不同配置

  5. API 使用

  6. 阅读 docs/API.md
  7. 查看示例代码

  8. 测试 API 端点

  9. 生产部署

  10. 阅读 docs/PRODUCTION_DEPLOYMENT.md
  11. 运行 ./demo_production_config.sh
  12. 部署到生产环境

📞 获取帮助

文档

  • 快速参考: CONFIG_QUICK_REFERENCE.md
  • 完整指南: CONFIGURATION_GUIDE.md
  • 技术实现: LOCALHOST_REMOVAL_SUMMARY.md
  • 演示索引: CONFIG_DEMO_INDEX.md

项目文档

  • 项目概述: README.md
  • 开发者指南: AGENTS.md
  • API 文档: docs/API.md
  • 生产部署: docs/PRODUCTION_DEPLOYMENT.md

故障排查

  1. 检查服务器日志
  2. 验证端口是否被占用
  3. 查看配置是否正确
  4. 参考 docs/README.md

📊 会话统计

代码变更: - 修改文件: 7 个 - 新增文件: 11 个 - 删除文件: 0 个

文档创建: - 配置文档: 5 个 - 演示脚本: 4 个 - 启动脚本: 1 个

问题修复: - 依赖缺失: 1 个 - 异步调用错误: 1 个 - 路由方法错误: 1 个 - 变量作用域错误: 1 个 - 端口占用: 1 个

功能实现: - 配置系统: ✅ 完成 - 环境变量支持: ✅ 完成 - 前端配置: ✅ 完成 - 演示脚本: ✅ 完成

🎉 总结

智桥服务器已成功启动并运行！本次会话完成了以下工作：

  1. ✅ 移除了所有硬编码的 localhost 引用
  2. ✅ 创建了灵活的配置系统
  3. ✅ 编写了完整的文档和演示
  4. ✅ 修复了启动过程中的所有问题
  5. ✅ 提供了统一的服务器启动脚本

现在您可以开始使用智桥的强大功能了！

文档版本: 1.0 最后更新: 2026-03-25 会话状态: ✅ 成功完成