Odysseus 最佳实践

本课程为云平台 Jupyter 实践课，在 Notebook 终端中完成启动与配置。Odysseus 已预装在 /home/atomgit/odysseus（dev 分支），无需克隆或安装依赖。

课程目标

学完本课程后，你将能够：

1. 在 Jupyter 终端中启动、停止 Odysseus 服务
2. 通过 Jupyter 代理地址访问 Web 界面并登录
3. 在 Settings 中配置 GitCode AI 模型
4. 使用 Chat、Agent 等核心功能完成一次完整体验

建议学时： 约 1 小时（含动手操作）

实践说明： 在 Jupyter 页面打开终端（Terminal），将下文代码块中的命令逐段复制执行。

第一章：认识 Odysseus

Odysseus 是一款自托管 AI 工作台——在服务器上提供类似 ChatGPT / Claude 的 Web 体验，数据留在你的工作区中。

本课程重点使用的功能：

更多功能（Cookbook、Deep Research、Documents、Email 等）可在登录后自行探索，详见官方仓库。

第二章：启动与访问

2.1 启动服务

参照官方 README Native Linux 流程：先运行 setup.py 配置管理员账号，再在 tmux 中启动 Web 服务。

步骤 1：初始化并配置管理员账号（首次使用）

cd /home/atomgit/odysseus
python3 setup.py

按终端提示设置管理员用户名与密码。请牢记此处设置的账号密码，后续登录使用。

若此前已执行过 setup.py，可跳过本步骤。

步骤 2：在 tmux 中启动服务

cd /home/atomgit/odysseus

ID=$(jupyter notebook list | grep -oP 'online-action/\K[a-f0-9]+' | head -1)

tmux new-session -d -s odysseus \
  "cd /home/atomgit/odysseus && ROOT_PATH=\"/online-action/${ID}/proxy/7000\" python -m uvicorn app:app --host 0.0.0.0 --port 7000 --root-path /online-action/${ID}/proxy/7000 2>&1 | tee /home/atomgit/odysseus/odysseus.log"

查看启动日志（可选）：

sleep 3
tail -50 /home/atomgit/odysseus/odysseus.log

进入 tmux 实时查看输出（Ctrl+B 再 D 退出会话、保持服务运行）：

tmux attach -t odysseus

说明：

• ID 来自 jupyter notebook list，用于 ROOT_PATH 与 --root-path，使反向代理路由正确
• 必须使用 --host 0.0.0.0，以便 Jupyter 代理能转发到 Odysseus
• 默认端口 7000；若被占用可换端口，并同步修改 ROOT_PATH、--root-path 及访问 URL

2.2 通过 Jupyter 访问 Odysseus

访问前，先确认服务已在运行：

tmux has-session -t odysseus 2>/dev/null && echo "tmux 会话 odysseus 运行中" || echo "未运行"
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:7000/

返回 200 或 302 后，获取访问地址：

ID=$(jupyter notebook list | grep -oP 'online-action/\K[a-f0-9]+' | head -1)
echo "========================================"
echo "  请点击或复制以下地址到浏览器访问 Odysseus："
echo "========================================"
echo "https://aihub-run.gitcode.com/online-action/${ID}/proxy/7000"
echo "========================================"

将链接复制到浏览器，使用 2.1 节 setup.py 中设置的账号密码 登录。

若 HTTP 探测未返回 200 或 302，请回到 2.1 节检查启动。若修改了端口，请将 URL 末尾的 7000 改为实际端口。

2.3 停止与重启

停止：

tmux kill-session -t odysseus

重启：

cd /home/atomgit/odysseus

ID=$(jupyter notebook list | grep -oP 'online-action/\K[a-f0-9]+' | head -1)

tmux kill-session -t odysseus 2>/dev/null

tmux new-session -d -s odysseus \
  "cd /home/atomgit/odysseus && ROOT_PATH=\"/online-action/${ID}/proxy/7000\" python -m uvicorn app:app --host 0.0.0.0 --port 7000 --root-path /online-action/${ID}/proxy/7000 2>&1 | tee /home/atomgit/odysseus/odysseus.log"

Jupyter 实例重启后，tmux 会话可能结束，需重新执行 2.1 或上表「重启」命令。

第三章：配置 GitCode AI 模型

3.1 创建 GitCode 访问令牌

1. 打开：https://gitcode.com/setting/token-classic
2. 新建经典访问令牌（Classic Token）
3. 创建后立即复制令牌并保存

3.2 在 Settings 中添加 API 模型

登录 Odysseus → Settings → Add Models → API Models，按下图填写：

先点 Test 确认连接成功，再点 Add 添加。

3.3 在 Chat 中验证

1. 进入 Chat，点击模型选择器
2. 选择 GitCode AI 返回的模型（如 deepseek-ai/DeepSeek-V4-Flash，以实际列表为准）
3. 发送一条消息，确认能正常回复

若 Test 失败，请检查：Endpoint URL 是否含 /v1、令牌是否有效、账户是否有 AI 权限。

第四章：核心功能体验

4.1 Chat（聊天）

1. Settings 中确认至少有一个可用模型
2. 进入 Chat，新建对话，选择模型
3. 尝试提问，可上传图片或 PDF 测试多模态（受大小限制）

4.2 Agent（智能体）

1. 进入 Agent 界面
2. 描述一个可执行的任务（如「总结当前目录下的 README 内容」）
3. 观察 Agent 调用工具并逐步完成

Agent 具备文件、Shell 等能力，请仅在可信环境中使用。

第五章：常见问题

5.1 页面打不开或代理 502

tmux has-session -t odysseus 2>/dev/null && tmux list-sessions | grep odysseus
curl -I http://127.0.0.1:7000/
tail -80 /home/atomgit/odysseus/odysseus.log

5.2 忘记管理员密码

cd /home/atomgit/odysseus
python3 setup.py

也可登录后在 Settings 中修改密码。

5.3 安全提示

• 使用 setup.py 设置足够强度的密码，勿与他人共享
• 通过 Jupyter 代理访问，不要将 Odysseus 端口单独暴露到公网
• 勿将 API Key、.env、data/ 中的密钥分享给他人

附录：快速参考

实践流程

打开 Jupyter 终端 → python3 setup.py（首次）→ tmux 启动（2.1）
    → 确认服务运行（2.2）→ 登录 → 配置 GitCode AI（第三章）→ Chat / Agent 体验

常用命令

# 访问地址
ID=$(jupyter notebook list | grep -oP 'online-action/\K[a-f0-9]+' | head -1)
echo "https://aihub-run.gitcode.com/online-action/${ID}/proxy/7000"

# 查看日志 / 进入 tmux / 停止 / 重启 — 见 2.1～2.3 节

官方资源

• 仓库：https://gitcode.com/gh_mirrors/ody/odysseus
• 环境分支：dev

Odysseus 最佳实践 · 云平台 Jupyter 实践课