软件研发部门MD文档图床使用说明

俯首为牛 2022-10-12 Hoeking 手机阅读

软件研发部门MD文档图床使用说明

一、背景

为了规范研发部门的文档管理，统一Markdown文档中的图片存储，我们搭建了专用的图床服务。本文介绍图床的使用方法。

二、图床服务

2.1 图床地址

环境 地址 用途
生产环境 https://mdimg.51epub.cc 正式文档使用
测试环境 http://test.51epub.cc 测试验证使用
本地环境 localhost:8080 本地开发使用

2.2 上传接口

POST /api/v1/upload
Content-Type: multipart/form-data

参数：
- file: 图片文件
- category: 图片分类（可选）

返回：
{
    "code": 200,
    "data": {
        "url": "https://mdimg.51epub.cc/2022/10/12/abc123.png"
    }
}

三、使用方法

3.1 PicGo工具

PicGo是一款好用的图床工具，支持多种图床服务。

3.1.1 安装配置

  1. 下载安装PicGo：https://github.com/Molunerfinn/PicGo
  2. 设置图床服务
  3. 配置API地址和密钥

3.1.2 使用步骤

  1. 截图或选择图片
  2. 复制图片到剪贴板
  3. 按快捷键上传（Ctrl+Shift+P）
  4. 自动复制Markdown格式的URL

3.2 命令行工具

3.2.1 安装

npm install -g mdimg-uploader

3.2.2 配置

mdimg config set --api https://mdimg.51epub.cc/api/v1/upload
mdimg config set --token your-token-here

3.2.3 使用

# 上传单个图片
mdimg upload image.png

# 上传并复制URL
mdimg upload image.png --copy

# 批量上传
mdimg upload *.png

3.3 IDE插件

3.3.1 VS Code插件

安装插件：Markdown Image

配置：

{
    "markdown-image.api": "https://mdimg.51epub.cc/api/v1/upload",
    "markdown-image.token": "your-token-here"
}

使用：粘贴图片自动上传

四、图片规范

4.1 命名规范

类型 命名规则 示例
架构图 arch_[模块]_[日期] arch_order_20221012.png
流程图 flow_[模块]_[日期] flow_return_20221012.png
界面图 ui_[模块]_[描述] ui_order_list.png
截图 shot_[功能]_[日期] shot_error_20221012.png

4.2 格式要求

要求 标准 说明
格式 PNG/JPG/GIF 优先PNG
尺寸 最大2000px 过长会自动压缩
大小 不超过2MB 过大需压缩
命名 小写+下划线 便于检索

4.3 存储目录

/
├── 2022/
│   ├── 01/
│   ├── 02/
│   └── ...
├── 2023/
│   ├── 01/
│   └── ...

按年月自动归档

五、文档规范

5.1 Markdown图片语法

![图片描述](图片URL)

5.2 示例

## 订单流程图

![订单流程图](https://mdimg.51epub.cc/2022/10/12/arch_order_20221012.png)

5.3 注意事项

  1. 图片URL要使用完整地址
  2. 图片描述要清晰明了
  3. 避免使用中文URL
  4. 定期检查图片可用性

六、常见问题

6.1 上传失败

问题 原因 解决方法
401错误 认证失败 检查token
413错误 文件过大 压缩图片
500错误 服务器异常 联系管理员

6.2 图片不显示

  1. 检查图片URL是否正确
  2. 确认图片已上传成功
  3. 检查网络是否正常
  4. 清除浏览器缓存

6.3 图片失效

  1. 定期备份重要图片
  2. 发现失效及时重新上传
  3. 使用相对稳定的服务

七、维护管理

7.1 图片清理

清理规则 周期 操作
临时图片 30天 自动清理
未引用图片 90天 提醒清理
过期文档图片 180天 归档处理

7.2 备份策略

  1. 图片服务每日备份
  2. 重要图片双重存储
  3. 定期验证备份完整性

7.3 权限管理

角色 权限
管理员 上传、删除、配置
开发者 上传、查询
访客 查询

八、联系方式

如有问题，请联系：

  • 运维组：ops@51epub.cc
  • 文档组：doc@51epub.cc

九、更新记录

版本 日期 更新内容 更新人
V1.0 2022-10-12 初稿发布 CLP
V1.1 2022-10-15 增加命令行工具 CLP


作者: CLP ; 日期: 2022-10-12 ; 地点: 武汉; 天气: 晴

QQ: 53258372; Mail : 53258372@QQ.com

微信: image-20220903114619121