你有没有过这种瞬间:文章写完了,评论区却冷清;读者卡在某个报错上,也不知道该把问题甩到哪里。
于是我想做一块「不打扰、但随时在」的入口——右下角一个圆按钮,点开就是对话。像 Crisp 那种客服浮层,但颜色要跟博客主题走,暗色模式也要跟着变。
最终落地很朴素:Alpine 浮层 + Django /chat/ + DeepSeek Flash。下面按「为什么这样选 → 怎么拼起来 → 关键代码 → 怎么配环境」写一遍,方便以后自己复盘,也方便你抄回家。
先看成品长什么样

打开站点后,右下角有一颗圆形聊天按钮(在「回到顶部」火箭上方一点)。
- 未登录:能看到欢迎语,底部是「登录 / 注册」,不能发消息
- 已登录:可以打字提问,助手用 Markdown 回你(标题、列表、代码都能正常显示)
- 换主题 / 暗色:气泡、顶栏、按钮颜色跟着 CSS 变量变,不用单独维护一套皮肤
欢迎语我故意写得轻松一点:
你好!我是 Jayfar 博客助手。登录后可以提问;有关于文章、技术或站点的问题,都可以问我 🙂
选型:为什么不是 Cursor / Ollama
做过几轮对比后,结论很干脆:
| 方案 | 结论 |
|---|---|
| Cursor 套餐 / SDK | 给写代码 Agent 用,贵、重,不适合公开访客聊天 |
| 本机 Ollama(3B/7B) | 2 核 2G 小机器直接出局,会和博客抢内存 |
| OpenAI 官方 | 国内直连不稳 |
| DeepSeek Flash | 国内可直连、按量便宜、OpenAI 兼容,刚好够博客答疑 |
所以:浮层自建,脑子租 DeepSeek。
整体结构(四块积木)
- 前端:
frontend/src/components/chatWidget.js(Alpine 组件) - 模板:
templates/share_layout/base.html挂载浮层 - 样式:
main.css里.jayfar-chat-*,全部吃--color-primary-*/--card等变量 - 后端:
blog/views.py的chat_assistant_view,路由POST /chat/
请求链路很短:
访客点发送
→ fetch('/chat/', { message, history })
→ 校验登录 / CSRF / 长度
→ 拼 system + 近期文章标题
→ DeepSeek chat.completions
→ 回 reply + reply_html(Markdown 渲染)
→ 气泡 x-html 展示
1)前端:登录门禁 + 发消息
组件注册在 main.js:Alpine.data('chatWidget', chatWidget)。
模板里把登录状态传进去(关键,别只靠前端藏输入框):
<div x-data="chatWidget({
authenticated: {% if user.is_authenticated %}true{% else %}false{% endif %},
loginUrl: '{% url 'account:login' %}',
registerUrl: '{% url 'account:register' %}'
})"
class="jayfar-chat-root">
发送逻辑核心如下——注意 credentials: 'same-origin' 和 X-CSRFToken,缺一个就会莫名失败:
async send() {
const text = (this.input || '').trim();
if (!text || this.sending) return;
if (!this.authenticated) {
// 前端先拦住;后端还会再拦一次
return;
}
this.messages.push({ role: 'user', content: text, html: '' });
this.sending = true;
const history = this.messages
.filter((m) => m.role === 'user' || m.role === 'assistant')
.slice(-8)
.map((m) => ({ role: m.role, content: m.content }));
const res = await fetch('/chat/', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-CSRFToken': getCookie('csrftoken'),
},
credentials: 'same-origin',
body: JSON.stringify({ message: text, history }),
});
const data = await res.json().catch(() => ({}));
this.messages.push({
role: 'assistant',
content: data.reply || '暂时没有回复。',
html: data.reply_html || '',
});
this.sending = false;
}
助手气泡用 x-html="bubbleHtml(msg)",优先展示后端渲染好的 reply_html。这样 **加粗**、`code` 不会再变成一坨乱符号。
2)后端:登录校验 + DeepSeek + Markdown
路由:
# blog/urls.py
path(r'chat/', views.chat_assistant_view, name='chat'),
第一道闸:必须登录
if not request.user.is_authenticated:
return JsonResponse({
'error': 'login_required',
'require_login': True,
'reply': '请先登录后再提问。',
'reply_html': f'<p>请先 <a href="{login_url}">登录</a> 后再提问。</p>',
}, status=401)
第二道闸:消息别太长(防刷)
message = (payload.get('message') or '').strip()
if len(message) > 2000:
return JsonResponse({'error': 'message too long'}, status=400)
调用 DeepSeek(关思考模式,更省)
from openai import OpenAI
client = OpenAI(api_key=api_key, base_url=base_url)
completion = client.chat.completions.create(
model=model, # 默认 deepseek-flash
messages=messages,
max_tokens=600,
extra_body={'thinking': {'type': 'disabled'}},
)
reply = (completion.choices[0].message.content or '').strip()
return JsonResponse({
'reply': reply,
'reply_html': CommonMarkdown.get_markdown(reply),
})
system 提示里会塞最近 8 篇已发布文章标题,让助手少胡编、多往本站内容靠:
recent = list(
Article.objects.filter(type='a', status='p')
.order_by('-pub_time')
.values_list('title', flat=True)[:8]
)
system = (
'你是个人博客的站点助手。用简洁中文回答。'
'使用标准 Markdown……优先结合本站内容……'
f'本站近期文章:{", ".join(recent) if recent else "暂无"}。'
)
3)配置:settings 读环境变量
djangoblog/settings.py:
OPENAI_API_KEY = (
os.environ.get('DEEPSEEK_API_KEY')
or os.environ.get('OPENAI_API_KEY')
or ''
).strip()
OPENAI_BASE_URL = (
os.environ.get('DEEPSEEK_BASE_URL')
or os.environ.get('OPENAI_BASE_URL')
or 'https://api.deepseek.com'
).strip().rstrip('/')
OPENAI_MODEL = (
os.environ.get('DEEPSEEK_MODEL')
or os.environ.get('OPENAI_MODEL')
or 'deepseek-flash'
).strip()
本机 PowerShell(关终端会丢,建议写进 run-local.ps1):
$env:DEEPSEEK_API_KEY="sk-你的key"
$env:DEEPSEEK_BASE_URL="https://api.deepseek.com"
$env:DEEPSEEK_MODEL="deepseek-flash"
.\.venv\Scripts\python.exe manage.py runserver 0.0.0.0:8000
线上(宝塔 / systemd)示例:
export DEEPSEEK_API_KEY="sk-你的key"
export DEEPSEEK_BASE_URL="https://api.deepseek.com"
export DEEPSEEK_MODEL="deepseek-flash"
踩过的坑:Key 复制时带了换行,请求头变成 Bearer \nsk-...\n,报 Illegal header value。所以配置里统一 .strip()。
4)主题跟随:别写死蓝色
浮层颜色不要写 #1E75EB 这种死值,用站点变量:
.jayfar-chat-fab {
background: rgb(var(--color-primary-500));
}
.jayfar-chat-panel {
background: rgb(var(--card));
color: rgb(var(--foreground));
border-color: rgb(var(--border) / 0.7);
}
.jayfar-chat-header {
background: linear-gradient(
135deg,
rgb(var(--color-primary-500)),
rgb(var(--color-primary-700))
);
}
换配色方案或暗色模式时,助手会自动变色——这是「像博客原生功能」而不是「贴了个第三方客服」的关键。
5)前端构建别忘了
改 JS/CSS 后:
cd frontend
npm run build
产物在 blog/static/blog/dist/,线上要带上新的 manifest 对应文件,硬刷新(Ctrl+F5)再测。
6)顺带:登录注册与邮件
助手强制登录后,账号链路也变重要了:
- 用户表:
accounts_bloguser(自定义用户,不是auth_user) - 后台可以管用户
- 忘记密码要发验证码,QQ 邮箱环境变量:
export DJANGO_EMAIL_HOST="smtp.qq.com"
export DJANGO_EMAIL_PORT="465"
export DJANGO_EMAIL_SSL="True"
export DJANGO_EMAIL_TLS="False"
export DJANGO_EMAIL_USER="你的QQ号@qq.com"
export DJANGO_EMAIL_PASSWORD="授权码" # 不是 QQ 登录密码
未配置时,点「获取验证码」会明确提示邮件服务未配置,而不是假装成功。
自测清单
- 未登录打开浮层 → 只有登录/注册,不能发送
- 登录后提问 → 有 Markdown 排版的回复
- 切换暗色 / 配色 → 按钮和顶栏颜色跟着变
- 不配
DEEPSEEK_API_KEY→ 返回引导文案,不报 500 - Key 前后有空格/换行 → 已被
.strip()消化
小结
博客助手不是「再挂一个大而全的 AI 平台」,而是:
- 一块跟主题走的小浮层
- 一条受登录保护的
/chat/ - 一个便宜能直连的
deepseek-flash
三块拼起来,访客有地方问,站长账单可控,站点气质也不碎。右下角那颗按钮,从此就不只是装饰了。
本文由 jayfar 原创,转载请注明出处。
评论
0