Chandra镜像保姆级教程：从零开始构建Chandra定制版——更换前端/添加插件/日志审计-程序员充电站

Chandra镜像保姆级教程：从零开始构建Chandra定制版——更换前端/添加插件/日志审计

1. 为什么你需要一个可定制的Chandra聊天助手

你有没有试过这样的场景：刚部署好一个AI聊天工具，用着挺顺手，但很快发现它缺个功能——比如想换掉那个默认的蓝色主题，换成深色护眼模式；或者希望每次对话都自动记录到日志里，方便后续复盘；又或者想给它加个代码高亮插件，让技术问答更清晰。这时候，你才发现，那个“开箱即用”的镜像，其实只是个起点。

Chandra不是另一个黑盒AI应用。它是一套可拆解、可替换、可审计的本地化聊天系统。它的名字来自梵语“月神”，象征智慧与澄明——而真正的智慧，不在于它能回答什么问题，而在于你能否真正理解它、掌控它、按需改造它。

本教程不讲“怎么启动一个容器”，而是带你亲手拆开Chandra的每一层：

把默认前端替换成你熟悉的UI框架（比如支持Markdown渲染增强的版本）
在Ollama后端无缝接入新插件（如敏感词过滤、上下文长度扩展）
实现细粒度日志审计——不只是“谁发了什么”，而是“请求耗时多少、模型响应是否截断、token使用量多少”

这不是一次配置练习，而是一次对AI服务底层逻辑的重新认知。你将获得的不是一个成品，而是一套可复用的定制方法论。

2. 环境准备与镜像基础结构解析

2.1 快速验证原始镜像是否正常运行

在动手改造前，先确认基础环境健康。假设你已通过CSDN星图镜像广场拉取并启动了Chandra镜像：

# 启动命令示例（请根据平台实际按钮或命令调整） docker run -d --name chandra -p 3000:3000 -v /path/to/data:/app/data csdn/chandra:latest

等待1–2分钟后，访问http://localhost:3000。你应该看到一个简洁的“Chandra Chat”界面，输入你好并回车，能看到gemma:2b模型以打字机效果实时回复。

小提示：如果页面空白或报错502，请先检查容器日志：
docker logs chandra | grep -E "(ollama|error|failed)"
大多数启动失败源于Ollama服务未就绪——Chandra的“自愈合”脚本需要约90秒完成初始化。

2.2 揭开镜像的三层结构：前端、API网关、Ollama内核

Chandra镜像并非单体应用，而是由三个明确分层构成的协作系统：

层级	位置	职责	可定制性
前端（Web UI）	`/app/frontend/`	用户交互界面、消息渲染、输入处理	（完全可替换）
API代理层	`/app/backend/`	接收HTTP请求、转发至Ollama、注入审计逻辑	（可添加中间件）
Ollama运行时	容器内独立进程	加载模型、执行推理、管理GPU/CPU资源	（仅限模型切换与参数调优）

这个分层设计是定制化的前提：你改前端，不影响后端；加审计日志，不改动模型加载逻辑。我们接下来的每一步操作，都会精准作用于对应层级，避免“牵一发而动全身”。

3. 更换前端：从默认UI到你想要的交互体验

3.1 理解默认前端的技术栈与文件结构

进入容器内部，查看前端目录：

docker exec -it chandra sh cd /app/frontend ls -l

你会看到类似结构：

dist/ # 构建后的静态文件（浏览器实际加载的内容） src/ # 源码（Vue 3 + TypeScript） package.json # 依赖与构建脚本 vite.config.ts # 构建配置（关键！）

默认前端基于Vite + Vue 3构建，轻量且现代。它的核心交互逻辑集中在src/views/ChatView.vue中——这里处理消息发送、流式接收、UI渲染。

为什么不用直接改dist？
dist/是构建产物，修改后重启容器会丢失。所有定制必须从源码层入手，再重新构建。

3.2 实战：替换为支持代码高亮与Markdown增强的前端

我们以集成vue3-markdown-it和highlight.js为例，让技术对话中的代码块自动高亮：

进入容器并安装依赖

docker exec -it chandra sh cd /app/frontend npm install markdown-it highlight.js vue3-markdown-it

修改src/main.ts注册插件

// src/main.ts import { createApp } from 'vue' import App from './App.vue' import MarkdownIt from 'vue3-markdown-it' import 'highlight.js/styles/github-dark.css' // 深色主题更护眼 const app = createApp(App) app.use(MarkdownIt, { html: true, linkify: true, typographer: true, highlight: (str, lang) => { if (!lang || !window.hljs) return str try { return window.hljs.highlight(str, { language: lang }).value } catch (__) { return str } } }) app.mount('#app')

在ChatView.vue中渲染Markdown

<!-- src/views/ChatView.vue --> <template> <div v-html="renderedMessage" class="message-content"></div> </template> <script setup> import { ref, onMounted } from 'vue' import MarkdownIt from 'markdown-it' const md = new MarkdownIt() const renderedMessage = ref('') const rawMessage = "```python\nprint('Hello World')\n```" renderedMessage.value = md.render(rawMessage) </script>

重新构建并替换静态文件

npm run build # 将新生成的dist复制到宿主机映射目录（假设你挂载了-v /host/dist:/app/dist） cp -r dist/* /host/dist/

重启容器后，你会发现所有AI返回的代码块都带上了语法高亮——无需改后端，不碰Ollama，纯前端增强。

4. 添加插件：为Ollama注入企业级能力

4.1 Ollama插件机制原理：不是“装插件”，而是“接管请求”

Ollama本身不提供传统意义上的插件市场。它的扩展能力体现在API代理层——即Chandra的后端服务。所有发往/api/chat的请求，都会先经过这个代理，再转发给Ollama。这正是我们注入能力的黄金位置。

Chandra后端是一个轻量Node.js服务（位于/app/backend/），核心文件是server.js。它用fetch调用本地Ollama API（http://localhost:11434/api/chat）。我们要做的，就是在fetch前后插入逻辑。

4.2 实战：添加敏感词实时过滤插件

目标：当用户输入含敏感词（如“破解”、“盗号”）时，前端显示友好提示，而非让模型生成违规内容。

在backend/server.js中添加过滤函数

// backend/server.js const SENSITIVE_WORDS = ['破解', '盗号', '绕过', '非法获取'] function containsSensitive(text) { return SENSITIVE_WORDS.some(word => text.includes(word)) } // 在处理POST /api/chat的路由中插入 app.post('/api/chat', async (req, res) => { const { message } = req.body // 新增：敏感词拦截 if (containsSensitive(message)) { return res.json({ error: '输入内容包含不适宜词汇，请修改后重试', type: 'sensitive_blocked' }) } // 原有逻辑：转发给Ollama const ollamaRes = await fetch('http://localhost:11434/api/chat', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(req.body) }) res.json(await ollamaRes.json()) })

前端适配错误提示在src/views/ChatView.vue的消息发送逻辑中，捕获type: 'sensitive_blocked'并展示提示：
```
if (response.type === 'sensitive_blocked') { addMessage({ role: 'system', content: response.error }) return }
```

这个插件没有修改Ollama一行代码，却实现了企业级内容安全控制——这就是Chandra架构的威力：能力扩展不依赖模型厂商，而由你完全掌控。

5. 日志审计：记录每一次对话的完整生命周期

5.1 审计什么？不只是“谁说了什么”

很多日志方案只记录原始输入输出，但这远远不够。真正的审计需要覆盖AI服务的全链路指标：

请求层：客户端IP、User-Agent、请求时间、耗时（毫秒）
模型层：使用的模型名（gemma:2b）、实际prompt token数、response token数、是否发生截断
响应层：最终返回状态（success/error）、错误类型（timeout/model_error）

这些数据组合起来，才能回答关键问题：
→ “为什么这个对话响应慢？” → 查看耗时+token数，判断是网络延迟还是模型计算瓶颈
→ “用户频繁触发截断错误？” → 统计context_length_exceeded出现频率，决定是否升级模型

5.2 实战：实现结构化JSON日志与审计看板

Chandra后端已内置日志模块（winston），我们只需增强其输出字段：

修改backend/server.js的日志配置

// backend/server.js const winston = require('winston') const logger = winston.createLogger({ level: 'info', format: winston.format.combine( winston.format.timestamp(), winston.format.json() // 关键：输出JSON格式，便于ELK等工具采集 ), transports: [ new winston.transports.File({ filename: '/app/logs/audit.log' }) ] }) // 在 /api/chat 路由中添加审计日志 app.post('/api/chat', async (req, res) => { const startTime = Date.now() const clientIP = req.ip || req.connection.remoteAddress try { const ollamaRes = await fetch('http://localhost:11434/api/chat', { /* ... */ }) const endTime = Date.now() const duration = endTime - startTime // 记录完整审计日志 logger.info('chat_audit', { timestamp: new Date().toISOString(), client_ip: clientIP, user_agent: req.get('User-Agent'), model: 'gemma:2b', prompt_tokens: estimateTokens(req.body.message), // 简单估算 response_tokens: estimateTokens(await ollamaRes.clone().text()), duration_ms: duration, status: 'success' }) res.json(await ollamaRes.json()) } catch (err) { logger.error('chat_audit_error', { client_ip: clientIP, error: err.message, status: 'failed' }) res.status(500).json({ error: '服务暂时不可用' }) } })

查看审计日志（实时滚动）

# 进入容器查看实时日志 docker exec -it chandra tail -f /app/logs/audit.log

你会看到类似结构化日志：

{ "timestamp": "2024-06-15T08:22:34.123Z", "client_ip": "::ffff:172.17.0.1", "user_agent": "Mozilla/5.0...", "model": "gemma:2b", "prompt_tokens": 12, "response_tokens": 87, "duration_ms": 428, "status": "success" }