netbox/NetBox前端定制化指南.md

# NetBox 前端定制化指南

本文档详细说明了如何自定义 NetBox 项目的前端元素，包括网站标题、LOGO、品牌元素等。

## 1. 页面标题修改

### 1.1 基础模板标题
**文件位置**: `netbox/templates/base/base.html`
**修改行**: 第 23 行
```html
<!-- 原始代码 -->
<title>{% block title %}{% trans "Home" %}{% endblock %} | NetBox</title>

<!-- 修改为 -->
<title>{% block title %}{% trans "Home" %}{% endblock %} | 您的公司名称</title>
```

### 1.2 浏览器标签页图标 (Favicon)
**文件位置**: `netbox/templates/base/base.html`
**修改行**: 第 45 行
```html
<!-- 原始代码 -->
<link rel="icon" type="image/png" href="{% static 'netbox.ico' %}" />

<!-- 需要替换的文件 -->
```
**需要替换的文件**: `netbox/project-static/img/netbox.ico`

### 1.3 移动端图标
**文件位置**: `netbox/templates/base/base.html`
**修改行**: 第 46 行
```html
<!-- 原始代码 -->
<link rel="apple-touch-icon" type="image/png" href="{% static 'netbox_touch-icon-180.png' %}" />
```
**需要替换的文件**: `netbox/project-static/img/netbox_touch-icon-180.png`

## 2. LOGO 修改

### 2.1 主导航栏 LOGO
**文件位置**: `netbox/templates/base/layout.html`
**修改行**: 第 32-35 行
```html
<!-- 原始代码 -->
<h1 class="navbar-brand pb-0">
  <a href="{% url 'home' %}">
    <img src="{% static 'logo_netbox_dark_teal.svg' %}" alt="{% trans "NetBox Logo" %}" class="navbar-brand-image hide-theme-dark">
    <img src="{% static 'logo_netbox_bright_teal.svg' %}" alt="{% trans "NetBox Logo" %}" class="navbar-brand-image hide-theme-light">
    <div class="netbox-edition fw-semibold text-center fs-5 my-1">{{ settings.RELEASE.edition }}</div>
  </a>
</h1>

<!-- 修改为 -->
<h1 class="navbar-brand pb-0">
  <a href="{% url 'home' %}">
    <img src="{% static 'your_logo_dark.svg' %}" alt="您的公司 Logo" class="navbar-brand-image hide-theme-dark">
    <img src="{% static 'your_logo_light.svg' %}" alt="您的公司 Logo" class="navbar-brand-image hide-theme-light">
    <div class="netbox-edition fw-semibold text-center fs-5 my-1">您的版本信息</div>
  </a>
</h1>
```

**需要替换的文件**:
- `netbox/project-static/img/logo_netbox_dark_teal.svg` (深色主题下的 LOGO)
- `netbox/project-static/img/logo_netbox_bright_teal.svg` (浅色主题下的 LOGO)

### 2.2 商业版装饰图案 (可选)
**文件位置**: `netbox/templates/base/layout.html`
**修改行**: 第 22-24 行
```html
<!-- 原始代码 -->
{% if settings.RELEASE.features.commercial %}
  <img class="motif" src="{% static 'motif.svg' %}" alt="{% trans "NetBox Motif" %}">
{% endif %}
```
**需要替换的文件**: `netbox/project-static/img/motif.svg`

## 3. 静态资源文件位置

### 3.1 图片资源目录
**主要目录**: `netbox/project-static/img/`

包含的文件:
- `logo_netbox_bright_teal.svg` - 浅色主题 LOGO
- `logo_netbox_dark_teal.svg` - 深色主题 LOGO  
- `motif.svg` - 装饰图案
- `netbox.ico` - 网站图标
- `netbox_icon.svg` - NetBox 图标
- `netbox_touch-icon-180.png` - 移动端图标
- `plugin-default.svg` - 插件默认图标
- `rest-api.ico` - REST API 图标

### 3.2 编译后的静态资源
**目录**: `netbox/project-static/dist/`
- 包含编译后的 CSS、JS 和字体文件
- 修改源文件后需要重新编译

## 4. 样式定制

### 4.1 CSS 源文件
**主要文件**: `netbox/project-static/styles/netbox.scss`
**变量文件**: `netbox/project-static/styles/_variables.scss`

### 4.2 自定义样式
**目录**: `netbox/project-static/styles/custom/`
- 可以在此目录添加自定义样式文件

## 5. 配置文件修改

### 5.1 横幅配置
**文件位置**: `netbox/configuration.py` (需要创建)

可配置的横幅选项:
```python
# 登录页面横幅
BANNER_LOGIN = "欢迎使用您的网络管理系统"

# 维护模式横幅  
BANNER_MAINTENANCE = "系统正在维护中，功能可能受限"

# 页面顶部横幅
BANNER_TOP = "您的公司内部网络管理系统"

# 页面底部横幅
BANNER_BOTTOM = "© 2024 您的公司名称"
```

### 5.2 REST API 文档标题
**文件位置**: `netbox/netbox/settings.py`
**修改行**: 第 733 行
```python
# 原始代码
'TITLE': 'NetBox REST API',

# 修改为
'TITLE': '您的公司 REST API',
```

## 6. 版本信息定制

### 6.1 版本显示
**文件位置**: `netbox/templates/base/layout.html`
**修改行**: 第 52-58 行
```html
<!-- 原始代码 -->
<div class="text-muted text-center fs-5 my-3">
  {{ settings.RELEASE.name }}
  {% if not settings.RELEASE.features.commercial and not settings.ISOLATED_DEPLOYMENT %}
    <div>
      <a href="https://netboxlabs.com/netbox-cloud/" class="text-muted">{% trans "Get" %} Cloud</a> |
      <a href="https://netboxlabs.com/netbox-enterprise/" class="text-muted">{% trans "Get" %} Enterprise</a>
    </div>
  {% endif %}
</div>

<!-- 可以修改为 -->
<div class="text-muted text-center fs-5 my-3">
  您的系统版本信息
  <!-- 移除或修改商业链接 -->
</div>
```

## 7. 搜索框定制

### 7.1 搜索占位符
**文件位置**: `netbox/templates/base/layout.html`
**修改行**: 第 75 行
```html
<!-- 原始代码 -->
<input type="text" name="q" value="" class="form-control" placeholder="Search…" aria-label="Search NetBox">

<!-- 修改为 -->
<input type="text" name="q" value="" class="form-control" placeholder="搜索..." aria-label="搜索您的系统">
```

## 8. 实施步骤

### 8.1 准备工作
1. 备份原始文件
2. 准备您的 LOGO 文件 (建议使用 SVG 格式)
3. 准备网站图标文件

### 8.2 文件替换
1. 将您的 LOGO 文件复制到 `netbox/project-static/img/` 目录
2. 修改模板文件中的引用路径
3. 更新配置文件

### 8.3 重新编译 (如果修改了样式)
```bash
cd netbox/project-static
npm install  # 如果是首次编译
npm run build
```

### 8.4 重启服务
```bash
# 重启 NetBox 服务以应用更改
sudo systemctl restart netbox
```

## 9. 注意事项

1. **备份**: 修改前请备份原始文件
2. **版本升级**: NetBox 升级时可能会覆盖自定义内容，需要重新应用修改
3. **图片格式**: 建议使用 SVG 格式的 LOGO，支持响应式和主题切换
4. **缓存**: 修改后可能需要清除浏览器缓存才能看到效果
5. **权限**: 确保 Web 服务器对静态文件有读取权限

## 10. 文件清单

需要修改或替换的主要文件:

### 模板文件
- `netbox/templates/base/base.html` - 页面标题和图标
- `netbox/templates/base/layout.html` - LOGO 和布局

### 静态资源文件
- `netbox/project-static/img/logo_netbox_dark_teal.svg`
- `netbox/project-static/img/logo_netbox_bright_teal.svg`
- `netbox/project-static/img/netbox.ico`
- `netbox/project-static/img/netbox_touch-icon-180.png`
- `netbox/project-static/img/motif.svg` (可选)

### 配置文件
- `netbox/configuration.py` - 横幅和基本配置
- `netbox/netbox/settings.py` - API 文档标题

通过以上修改，您可以将 NetBox 完全定制为您自己的品牌形象。